# Picabird

> Fresh data from the system of record, as compact typed records your agent can use directly. Ask about clinical trials, FDA recalls, Federal Register rules and notices (including FERC grid documents) or SEC filings, and get back records read from the official source at request time. Shopping agents: product listings with comparable specs and live, landed prices are in early access. You get exact filters instead of fuzzy search, typed fields with ISO dates, and provenance on every field: the source URL, when it was fetched, and where each value came from. Free and keyless during early access (about 30 requests per minute).

## Why agents use it
- **Fresh:** read from the official source at request time, or from a cache no older than `max_age_hours` (set 0 to force a live read). Each record says `retrieved_at` and `cache: live|cached`.
- **Small:** a record is a few hundred tokens instead of a 30 KB source document. `usage.source_bytes` vs `usage.response_bytes` shows the difference on every call.
- **Exact:** phase, status, dates, recall class and form type are exact predicates run by the source. The only thing a model does is read your question, and that interpretation comes back in `interpreted.notes`.
- **Grounded:** `provenance.paths` maps each field to its path in the source record. `matched[].evidence` quotes the text that matched. Unknown values are null, never guessed.
- **Predictable:** unknown fields and filters return a 400 that names them. Errors are `{error: {type, code, message, param}}`.

## Endpoints
Base URL: https://picabird.ai. Full schema: https://picabird.ai/openapi.json

- `POST /v1/search`: `{"query": "natural language"}` (add `"source"` to force a source) or `{"source": "...", "filters": {...}}`. Optional: `limit` (1-10, default 5), `fields` (keep only these record fields), `cursor` (from `next_cursor`), `max_age_hours` (0-24, default 1).
- `POST /v1/interpret`: `{"query": "..."}`. Shows the parsed `{source, filters, notes}` without fetching.
- `GET /v1/records/{id}`: one record. IDs: `ctgov:NCT07539311`, `openfda:enforcement:D-0082-2027`, `fedreg:2026-22396`, `edgar:0001104659-26-120212`. Optional `?max_age_hours=0`.
- `POST /v1/watches`: `{"query", "webhook_url" or "email"}`. Saved for early access; delivery is not running yet.
- Send `Accept: text/markdown` to /v1/search for a compact table instead of JSON.

## Response
`{request_id, interpreted:{source, filters, notes[]}, results:[record], total, next_cursor, notices[], warnings[], usage:{records, response_bytes, source_bytes, source_requests}, freshness:{max_age_hours, served_from}, cost:{usd}, timing_ms}`.
`notices` are written for you, the model (source caveats). `warnings` are for the developer (a source failed, a fallback was used).

## Record (picabird.record@1)
`{id, schema, kind, title, summary, event:{type, date}, fields:{...}, entities[], matched:[{criterion, field, evidence, weak?}], provenance:{source, url, api_url, retrieved_at, source_updated_at, cache, paths}}`.
`summary` is assembled from fields by code. `matched[].weak = true` means the source matched the term in full text, but it is not in the title or abstract.

## Sources
- `ctgov`: ClinicalTrials.gov API v2. Clinical trial registrations (NIH/NLM). Updated daily.
  Filters: `condition` (string), `term` (string), `intervention` (string), `sponsor` (string), `phase` (enum[]: EARLY_PHASE1 | PHASE1 | PHASE2 | PHASE3 | PHASE4 | NA), `status` (enum[]: RECRUITING | NOT_YET_RECRUITING | ACTIVE_NOT_RECRUITING | ENROLLING_BY_INVITATION | COMPLETED | SUSPENDED | TERMINATED | WITHDRAWN), `updated_since` (date), `updated_until` (date)
- `openfda`: openFDA enforcement reports. FDA recall enforcement reports for drugs, devices and food. Updated weekly.
  Filters: `category` (enum: drug | device | food), `classification` (enum: Class I | Class II | Class III), `status` (enum: Ongoing | Completed | Terminated), `firm` (string), `term` (string), `reported_since` (date), `reported_until` (date)
- `fedreg`: Federal Register API. US Federal Register: rules, proposed rules, notices, presidential documents. Published each business day.
  Filters: `term` (string), `agencies` (string[]), `type` (enum[]: RULE | PRORULE | NOTICE | PRESDOCU), `published_since` (date), `published_until` (date)
- `edgar`: SEC EDGAR full-text search. SEC EDGAR filings full-text search (2001 onward). Near real time.
  Filters: `term` (string), `forms` (enum[]: 8-K | 10-K | 10-Q | S-1 | 6-K | 20-F | DEF 14A | SC 13D | SC 13G | 4 | 424B4), `filed_since` (date), `filed_until` (date)
- ISO/RTO interconnection queues (MISO, ERCOT, PJM...): early access. For grid questions now, try FERC documents via the Federal Register.
- Agent shopping (`source: "shopping"`): early access. Every listing in a category from marketplaces and brand stores, with comparable specs and the exact variant's live, landed price. Nobody pays to rank. Buying questions return this source with a notice and no results for now.

## Example
```
curl -s https://picabird.ai/v1/search -H 'content-type: application/json' \
  -d '{"query": "phase 2 oncology trials updated in the last 30 days", "limit": 3}'
```

```
curl -s https://picabird.ai/v1/search -H 'content-type: application/json' \
  -d '{"source": "openfda", "filters": {"category": "drug", "classification": "Class I", "reported_since": "2026-10-01"}}'
```

## Example questions
- phase 2 oncology trials updated in the last 30 days
- class I drug recalls in the last 30 days
- proposed rules mentioning "air quality" in the last 30 days
- FERC notices and rules mentioning "interconnection" in the last 30 days
- recruiting GLP-1 trials
- device recalls in the last 30 days