# Picabird

> Live, structured records from official public sources (clinical trials, FDA recalls, the Federal Register, SEC filings, and FERC grid rules via the Federal Register) for AI agents. Every record carries field-level provenance back to the source. Records contain only source facts; summaries are built by code, not by an LLM. Free and keyless during early access (about 30 requests per minute per IP).

## Endpoints
Base URL: https://www.picabird.ai

- `POST /v1/search`: body `{"query": "natural language"}` or `{"source": "...", "filters": {...}}`. Optional `limit` (1-10, default 5), `fields` (array of field names to keep), `cursor` (from `next_cursor`). Unknown fields return 400; nothing is ignored silently.
- `POST /v1/interpret`: body `{"query": "..."}`. Shows how the question is parsed into `{source, filters, notes}` without fetching anything.
- `GET /v1/records/{id}`: one record, read live. IDs: `ctgov:NCT07539311`, `openfda:enforcement:D-0082-2027`, `fedreg:2026-22396`, `edgar:0001104659-26-120212`.
- `POST /v1/watches`: `{"query", "webhook_url" or "email"}`. Stored for early access; not yet running.
- `POST /v1/early-access`: `{"email", "company"?, "dataset_wanted"?, "use_case"?}`.
- 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[], cost:{usd}, timing_ms}`.
`notices` are for 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: live|cached, paths:{field: source path}, terms}}`.
Dates are ISO 8601. Unknown values are null and never inferred. `matched[].weak = true` means the source's index matched but the term is not visible 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, pending permission from each publisher.

## Example
```
curl -s https://www.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://www.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