API overview

The BioSkepsis API puts a full research run behind a REST endpoint. Your product posts a life-science question, follows the run while the agent searches and reads full text, and gets back the same citation-grounded brief a user would see in the BioSkepsis app.

#What the API gives you

A research run is not a search call. When you start one, BioSkepsis plans the question into sub-questions, searches 40M+ papers, reads full text rather than abstracts, screens out retracted and hijacked-journal sources, verifies every claim against the passage behind it, and returns a brief with ranked sources, sub-question coverage, and a Trust Index. That work takes minutes, not milliseconds, so the API is built around a run lifecycle rather than a single request/response.

The v1 API covers four things:

• Starting and following runs. Create a run, poll its status or stream its progress, then fetch the finished brief.
• Reading saved briefs. List the briefs on the key owner's account and fetch any one of them by id.
• Creating research feeds. Turn a finished run into a scheduled email feed that follows new papers on the same topic.
• Predictable failure. One error envelope and a fixed set of codes, so your integration can branch on a string instead of parsing prose.

#Base URL and reference

Every endpoint lives under a single versioned prefix. Paths in these pages are written relative to it.

https://app.bioskepsis.ai/api/v1

An interactive reference, generated from the live service and titled BioSkepsis API, is served at app.bioskepsis.ai/api/v1/docs, with the raw OpenAPI document at /api/v1/openapi.json. Use it to generate a client or to check exact response fields; use these pages for the behaviour around the endpoints, which a schema cannot express.

#Authentication

The API authenticates with API keys, not user sessions. In the BioSkepsis app, open your avatar menu, then Settings, then API keys, and create one. The key is displayed once at creation and never again, so store it in your secret manager the way you would store a database password.

Send the key on every request, in either of two equivalent headers:

Authorization: Bearer bsk_live_...
X-API-Key: bsk_live_...

A minimal authenticated call looks like this:

curl https://app.bioskepsis.ai/api/v1/briefs?limit=1 \
  -H "Authorization: Bearer $BSK_KEY"

A missing, malformed, revoked, or wrong-environment key is rejected with 401 invalid_api_key. Keys carry the permissions of the account that created them, so a key is as sensitive as the account behind it: rotate it if it leaks, and never ship it in client-side code where a browser or a mobile app can read it.

#Environments

Keys are bound to the environment that issued them. Production keys are prefixed bsk_live_ and work against the production host. Staging issues bsk_test_ keys, and those only work against the staging host. Presenting a key to the wrong environment returns 401 invalid_api_key rather than a more specific error, so if authentication fails unexpectedly, check the prefix against the host you are calling before anything else.

#Billing and usage

API usage is not billed separately. A run started through the API draws on the key owner's normal BioSkepsis plan exactly as a run started in the app does: it consumes the monthly brief allowance first, then prepaid credits. When neither is available, the start request fails with a 402 and a code that tells you which of the two ran out.

That matters for how you design the integration. If your product runs BioSkepsis on behalf of many of your own users against a single key, they all share one allowance, and one heavy user can exhaust it for everyone. Surface the 402 codes in your own UI rather than treating them as generic failures, so the account owner knows to top up.

#The error envelope

Every error, at every status code, has the same shape. Branch on code; show message to a human; read details when a code documents it.

{
  "error": {
    "code": "credits_exhausted",
    "message": "Your monthly allowance and prepaid credits are used up.",
    "details": { "credits_available_cents": 0 }
  }
}

The full list of codes, which are retryable, and which are permanent, is on the endpoints, errors & limits page.

#Where to go next

Read the API quickstart next for a working start-to-brief integration, including idempotent starts and how to consume the progress stream without double-processing events. Then keep the reference open for the endpoint list, the error table, and the rate and concurrency limits your client has to respect.