// api reference

live data for agents

The Picabird API turns an agent's question into compact, typed records read from the system of record, with every value traced back to where it came from.

Ask in plain English or with exact filters. Picabird queries ClinicalTrials.gov, openFDA, the Federal Register or SEC EDGAR when you ask, and returns records in one envelope with the same shape every time.

what you get

• Freshness. Data is read from the source when you ask. You set the oldest cached copy you accept with max_age_hours; 0 reads live.
• Accuracy. Every field carries a provenance path into the source's own API response, so you can verify it. Summaries are built by code, never by a model, and unknown values are null.
• Token efficiency. Typed fields instead of raw records: a ClinicalTrials.gov study is about 34 KB of nested JSON. Every response reports usage, so you can see the bytes read against the bytes returned.
• Exact filters. Phase, recall class, form type and dates run as exact predicates at the source. An unknown filter or a bad value returns 400; nothing is ignored silently.
• Coverage. Clinical trials, FDA recalls, federal rules and notices (including FERC), and SEC filings are live. Product listings and live prices for shopping agents are in early access. More sources are coming.
• Domain capabilities. Phrase evidence in matched, source caveats in notices, and watches that store a question today, with change delivery and field diffs coming.

base url

All endpoints live under https://picabird.ai. Requests and responses are JSON over HTTPS. CORS is open, so you can call the API from a browser.

authentication

None during early access. There is no API key yet: send requests without an Authorization header. Keys will arrive with paid plans, and this page will say so first.

at a glance

• Rate limit: 30 requests per minute per IP. See Rate limits.
• Cost: free. Every response carries cost.usd: 0.
• Every response has a request_id. Quote it if you write to hello@picabird.ai.

https://picabird.ai

POST /v1/search
POST /v1/interpret
GET  /v1/records/:id
GET  /v1/sources
GET  /v1/presets
POST /v1/early-access
POST /v1/watches   # early access
GET  /llms.txt
GET  /openapi.json

quickstart

Your first call takes one command and no key.

1. Copy the request from the code panel, in curl, Python or JavaScript.
2. Run it. You get recent Class I drug recalls from openFDA as records.
3. Read interpreted to see how your question was understood, then results[].provenance.url to check any record at its source.

Or press Send below to run it from this page.

next steps

• Swap query for exact filters: see structured queries.
• Keep only the fields you need with fields: see projection.
• Wiring an agent? Read For agents.

// concepts

natural-language and structured queries

Every search is either a query in plain English or a source with filters.

Natural language is the quickest way to start. Picabird reads the question with a rule parser, picks a source and builds filters. When the rules are unsure, a model may read the question instead. Either way, the result is returned in interpreted.

Structured queries skip interpretation. You name the source and send its filters, which are validated exactly: an unknown filter, a bad date or an out-of-range value returns 400. Nothing is ignored silently.

Use natural language while exploring, then copy interpreted.source and interpreted.filters into a structured query for repeatable results.

With query you may also send source as a hint, which forces the source. Sending both query and filters returns 400 conflicting_parameters.

interpretation and notes

interpreted says which source and filters ran, and notes explain each decision in plain English.

Read the notes before trusting a natural-language result. "Last 30 days" becomes a dated filter, "phase 2" becomes PHASE2, and each mapping is written down. Structured queries return the single note filters given explicitly; no interpretation applied.

To check a question without fetching anything, call POST /v1/interpret. It returns the same interpreted object plus method (rules or ai) and the rule parser's confidence.

If no source fits, the API returns 400 source_not_determined and suggests words to use. Questions about ISO/RTO interconnection queues return source: "iso_queue", and shopping questions ("cheapest … in stock", "under S$500 landed in Singapore") return source: "shopping". Both come back with no results and a notice while those sources are in early access.

notices and warnings

notices are caveats for the model; warnings are problems for the developer.

Notices travel with the data. Pass them to your model with the records: "openFDA results are unvalidated", "this term search is noisy", "the source does not publish amendment diffs".

Warnings mean something went wrong on the way: a source failed or timed out, or the AI interpreter failed and the rule parser was used. Log them. A search whose source fails still returns 200, with empty results and a warning, so one bad upstream does not crash your agent.

provenance

Every record says where each value came from and when we fetched it, so an agent can cite it and you can check it.

• url is the human page at the source; api_url is the exact request we made.
• retrieved_at is when we fetched it; source_updated_at is when the source last updated, if it says.
• paths maps each record field to the source's own field, so fields.phase points at protocolSection.designModule.phases.
• api_root says where the record sits in the api_url response, so paths resolve exactly. derived lists the few keys Picabird computes, such as fields.category, which have no single source path.

matched explains fuzzy matches. Each entry names the criterion, the field it was found in, and a snippet of evidence. weak: true means the source's index matched but the term is not visible in the title or abstract, so treat it with care.

The summary line is assembled from fields by code, never by a model.

check a total yourself

Search responses include interpreted.upstream: the exact public request behind total, with the JSON path to the source's own count. Re-run it to compare. When our total differs from the source's, as with EDGAR, which counts documents rather than filings, a notice says why.

freshness and caching

You choose how old the data may be with max_age_hours; every record says whether it was read live.

Picabird caches what it reads from a source for up to 24 hours. A request uses a cached copy only if it is younger than max_age_hours, from 0 to 24 and 1 by default. Send 0 to force a live read. POST /v1/search takes it in the body; GET /v1/records/:id takes it as a query parameter.

• provenance.cache is live or cached for each record.
• provenance.retrieved_at is when we actually fetched from the source, even on a cache hit.
• freshness.served_from sums up the response: live, cache or mixed.

Sources update on their own schedules: ClinicalTrials.gov daily, openFDA enforcement reports weekly, the Federal Register each business day, and EDGAR in near real time. A fresh fetch cannot return data the source has not published yet; when that explains an empty result, a notice says so.

Calls to a source time out after 8 seconds. In a search, a timeout becomes a warning, not an error.

usage

Search and record responses include usage: the records returned, response_bytes, the source_bytes we read to build the response, and source_requests. The gap between source_bytes and response_bytes is the raw data your agent did not have to read. The consoles on this page chart it after each call.

unknown values are null

If the source does not say, the value is null. Picabird never guesses or fills in.

Dates are ISO 8601. A date the source gives only to the month stays a month, as in "2028-09". Lists are empty arrays, never null. total is null when a source does not report a count, as with EDGAR, whose hits are documents rather than filings.

pagination and projection

Page with cursor; trim records with fields.

limit takes 1 to 10 records (default 5). When more exist, next_cursor is a string; send it back as cursor with the same query to get the next page. It is null on the last page. A cursor belongs to one source, and using it with another returns 400.

fields keeps only the listed keys in each record's fields object, and trims provenance.paths to match. The envelope (id, title, summary, event, provenance) is always returned. Field names are listed per source under Objects.

// reference

sources and filters

Each live source, how often it updates, and the exact filters it takes.

Use a source's filters with source + filters in POST /v1/search. Field names for fields are listed under each source's schema.

coming

Want one of these, or something else? Tell us the dataset you can't get.

errors

Picabird uses HTTP status codes and returns a JSON error object with a stable code.

2xx means success, 4xx means the request needs fixing, and 5xx means something failed on our side or at the source. Branch on error.code, not on message, which may change.

status codes and error codes

A source that fails during a search does not produce an error: you get 200 with empty results and a warning.

rate limits

During early access, each IP address can make 30 requests per minute across /v1/*.

Over the limit, the API returns 429 rate_limit_exceeded with a Retry-After: 60 header. Wait that many seconds, then retry. Back off rather than retrying in a loop.

The limit counts per fixed one-minute window and is applied on a best-effort basis. Need more? Ask for early access and tell us your volume.

A repeated query within your max_age_hours is served from cache and comes back cached, which keeps it fast.

versioning

The URL carries the API version, and every record names the schema version of its fields.

• API: /v1. A breaking change to endpoints would ship under a new path.
• Envelope: picabird.record@1, the shape documented under The record object.
• Fields: record.schema, such as ctgov.study@1, versions each source's fields separately.

Within a version, we only add: new keys in fields, new optional keys in responses, new sources. Removing, renaming or retyping a field ships as a new version, such as ctgov.study@2, so a change is visible in the data itself.

Write clients that ignore keys they don't know. Check schema if you depend on a field's exact type.

for agents

Picabird is built to be read by models: one compact envelope, explicit nulls, caveats in notices, and a byte count in usage.

llms.txt

Point your agent at /llms.txt. It describes every endpoint, the record shape and each source's filters in about one page of plain text.

markdown responses

Send Accept: text/markdown to POST /v1/search to get a short table with the interpretation, source links, notices and the next cursor. It suits agents that read results rather than parse them.

openapi

/openapi.json describes the API for tool registration and client generation.

mcp coming

A hosted MCP server is planned and not available yet. Until then, register POST /v1/search as a tool from the OpenAPI spec.

tips

• Give the model notices along with results.
• Use fields to keep context small.
• Ask the model to cite provenance.url for every claim.