Overview API keys allow you to integrate Preclinical into your CI/CD pipelines, automation workflows, and custom tooling. With an API key, you can programmatically:
Start test runs against your AI agents
Poll for run status and results
Manage agents and test suites
Retrieve detailed test results for analysis
Creating an API Key
Navigate to Settings in the sidebar
Click API Keys tab
Click Create API Key
Give your key a descriptive name (e.g., “CI/CD Pipeline”, “Staging Tests”)
Optionally set an expiration date
Click Create
Your API key is only shown once at creation. Copy it immediately and store it securely.
If you lose your key, you’ll need to create a new one.
API keys follow this format:
sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
sk_live_ prefix identifies it as a live API key40 random alphanumeric characters for security
Using Your API Key Include the API key in the Authorization header of all API requests:
curl -X GET https://app.preclinical.dev/api/v1/runs \ -H "Authorization: Bearer sk_live_your_api_key_here"
Environment Variable Store your API key in an environment variable:
export PRECLINICAL_API_KEY = "sk_live_your_api_key_here"
Then use it in your scripts:
curl -X POST https://app.preclinical.dev/api/v1/runs \ -H "Authorization: Bearer $PRECLINICAL_API_KEY " \ -H "Content-Type: application/json" \ -d '{"agent_id": "your-agent-id"}'
CI/CD Integration Example GitHub Actions name : Run Preclinical Tests on : push : branches : [ main ] pull_request : jobs : test : runs-on : ubuntu-latest steps : - name : Start Preclinical Test Run env : PRECLINICAL_API_KEY : ${{ secrets.PRECLINICAL_API_KEY }} run : | # Start the test run RUN_RESPONSE=$(curl -s -X POST https://app.preclinical.dev/api/v1/runs \ -H "Authorization: Bearer $PRECLINICAL_API_KEY" \ -H "Content-Type: application/json" \ -d '{"agent_id": "${{ vars.AGENT_ID }}", "test_mode": "demo"}') RUN_ID=$(echo $RUN_RESPONSE | jq -r '.id') echo "Started run: $RUN_ID" # Poll until complete while true; do STATUS=$(curl -s https://app.preclinical.dev/api/v1/runs/$RUN_ID \ -H "Authorization: Bearer $PRECLINICAL_API_KEY" | jq -r '.status') if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then break fi sleep 5 done # Check results RESULT=$(curl -s https://app.preclinical.dev/api/v1/runs/$RUN_ID \ -H "Authorization: Bearer $PRECLINICAL_API_KEY") PASS_RATE=$(echo $RESULT | jq -r '.pass_rate') echo "Pass rate: $PASS_RATE%" # Fail if pass rate is below threshold if (( $(echo "$PASS_RATE < 80" | bc -l) )); then echo "Test run failed: pass rate below 80%" exit 1 fi
Key Management Viewing Keys All your API keys are listed in Settings > API Keys . You can see:
Key name
Creation date
Last used timestamp
Expiration date (if set)
Revoking Keys To revoke a key:
Go to Settings > API Keys
Click the trash icon next to the key
Confirm deletion
Revoking a key immediately invalidates it. Any integrations using that key will fail.
Best Practices
Use Separate Keys Create different keys for different environments (staging, production) and purposes (CI/CD, monitoring).
Set Expiration Set expiration dates on keys to enforce regular rotation.
Never Commit Keys Store keys in environment variables or secret managers. Never commit them to version control.
Monitor Usage Check the “last used” timestamp regularly to identify unused keys for cleanup.
Next Steps 
