{ "openapi": "3.1.0", "info": { "title": "Picabird API", "version": "0.1.0", "summary": "Live, typed records from official public sources, built for AI agents.", "description": "Picabird turns a question into an exact query against an official source and returns compact records (`picabird.record@1`) with field-level provenance.\nThe only thing a model does is interpret the question, and that interpretation is always returned in `interpreted`. Record content comes from the source alone: summaries are assembled by code, and unknown values are null.\n\n**Rate limits.** 30 requests per minute per IP across `/v1/*`. Going over returns 429 `rate_limit_exceeded` with a `Retry-After` header. Upstream limits also apply; see `x-picabird-sources`.\n\n**Freshness.** Upstream responses are cached for up to 24 h. `max_age_hours` (0-24, default 1) sets the oldest cached response you will accept; 0 forces a live read. Each record says `provenance.cache: live|cached` with `retrieved_at`, and each response has `freshness.served_from`.\n\n**Usage.** Every search and record response has `usage: {records, response_bytes, source_bytes, source_requests}`. `source_bytes` is the raw (decoded) upstream JSON we read to build the response; on a cache hit it is the size stored with the cache entry. For ClinicalTrials.gov we read full study records (no `fields=` projection), so `source_bytes` is the exact size of the full records an agent would otherwise download. For the Federal Register with a `term`, it covers the newest 100 matches we rank.\n\n**Errors.** Every error is `{error: {type, code, message, param?}, request_id}`.\n\n| code | HTTP | type | meaning |\n|---|---|---|---|\n| `invalid_json` | 400 | `invalid_request` | The body is not valid JSON, or is not a JSON object. |\n| `unknown_field` | 400 | `invalid_request` | A top-level body field, query parameter or `fields` entry is not supported. `param` names it. |\n| `unknown_filter` | 400 | `invalid_request` | A filter is not supported by the chosen source. `param` is `filters.`. |\n| `unknown_source` | 400 | `invalid_request` | `source` is not one of the registered sources. |\n| `missing_parameter` | 400 | `invalid_request` | A required field is missing, e.g. neither `query` nor `source` was sent. |\n| `missing_filter` | 400 | `invalid_request` | The source needs at least one filter (ctgov) or a term/forms filter (edgar). |\n| `conflicting_parameters` | 400 | `invalid_request` | `query` and `filters` were both sent. Send one or the other (`source` may accompany `query` as a hint). |\n| `invalid_value` | 400 | `invalid_request` | A value has the wrong type, format or range (dates are YYYY-MM-DD, limit is 1-10, max_age_hours is 0-24). |\n| `invalid_cursor` | 400 | `invalid_request` | `cursor` was not issued for this source. |\n| `invalid_id` | 400 | `invalid_request` | A record id is malformed or has an unknown source prefix. |\n| `source_not_determined` | 400 | `invalid_request` | The question names no recognisable source and no AI interpreter was available. Mention trials, recalls, rules or a form type, or pass `source`. |\n| `method_not_allowed` | 405 | `invalid_request` | The endpoint exists but not for this HTTP method. |\n| `endpoint_not_found` | 404 | `not_found` | No such endpoint. |\n| `record_not_found` | 404 | `not_found` | The source has no record with this id. |\n| `rate_limit_exceeded` | 429 | `rate_limited` | More than 30 /v1 requests in a minute from one IP. Retry after the `Retry-After` header (seconds). |\n| `upstream_error` | 502 | `upstream_unavailable` | The official source failed or timed out (8 s) while reading a single record. Searches report this as a warning instead. |\n| `source_unavailable` | 503 | `upstream_unavailable` | The source is not enabled (ISO/RTO queues are in early access). |\n| `storage_unavailable` | 503 | `upstream_unavailable` | The database is unavailable, so a sign-up or watch could not be stored. |\n| `internal_error` | 500 | `api_error` | An unexpected error on our side. |", "contact": { "email": "hello@picabird.ai" } }, "servers": [ { "url": "https://picabird.ai" } ], "x-picabird-sources": [ { "id": "ctgov", "name": "ClinicalTrials.gov API v2", "description": "Clinical trial registrations (NIH/NLM). Updated daily.", "status": "live" }, { "id": "openfda", "name": "openFDA enforcement reports", "description": "FDA recall enforcement reports for drugs, devices and food. Updated weekly.", "status": "live" }, { "id": "fedreg", "name": "Federal Register API", "description": "US Federal Register: rules, proposed rules, notices, presidential documents. Published each business day.", "status": "live" }, { "id": "edgar", "name": "SEC EDGAR full-text search", "description": "SEC EDGAR filings full-text search (2001 onward). Near real time.", "status": "live" }, { "id": "iso_queue", "status": "early_access", "notice": "ISO/RTO interconnection queues are in early access. FERC rules and notices are available now: try `FERC notices mentioning \"interconnection\"`." }, { "id": "shopping", "status": "early_access", "notice": "Agent shopping is in early access: every listing in a category as typed records, with comparable specs and the exact variant's live, landed price. Tell us the category you need at https://picabird.ai/#access." } ], "tags": [ { "name": "Search", "description": "Query live sources." }, { "name": "Records", "description": "Read one record by id." }, { "name": "Early access", "description": "Sign-ups and watches (stored, not yet run)." }, { "name": "Meta", "description": "Presets, sources and machine-readable docs." } ], "paths": { "/v1/search": { "post": { "tags": [ "Search" ], "operationId": "search", "summary": "Search a source with a question or with exact filters", "description": "Send `query` (natural language, optionally with a `source` hint) or `source` + `filters`. Sending `query` together with `filters` is a 400. With `Accept: text/markdown` the same data comes back as a compact table. A failing source becomes a `warnings` entry, not an error.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "examples": { "question": { "value": { "query": "phase 2 oncology trials updated in the last 30 days", "limit": 3 } }, "filters": { "value": { "source": "openfda", "filters": { "category": "drug", "classification": "Class I", "reported_since": "2026-10-01" } } }, "hint": { "value": { "query": "pipeline safety", "source": "fedreg", "max_age_hours": 0 } } } } } }, "responses": { "200": { "description": "Results. `results` may be empty; check `notices` and `warnings`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } }, "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request. Codes: `invalid_json`, `unknown_field`, `unknown_filter`, `unknown_source`, `missing_parameter`, `missing_filter`, `conflicting_parameters`, `invalid_value`, `invalid_cursor`, `source_not_determined`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Codes: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/interpret": { "post": { "tags": [ "Search" ], "operationId": "interpret", "summary": "Show how a question would be parsed, without fetching", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 500 }, "source": { "type": "string", "enum": [ "ctgov", "openfda", "fedreg", "edgar" ], "description": "Optional hint that forces the source." } } } } } }, "responses": { "200": { "description": "The interpretation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "interpreted": { "$ref": "#/components/schemas/Interpreted" }, "method": { "type": "string", "enum": [ "rules", "ai" ] }, "confidence": { "type": "number" }, "warnings": { "type": "array", "items": { "type": "string" } }, "cost": { "$ref": "#/components/schemas/Cost" }, "timing_ms": { "type": "integer" } } } } } }, "400": { "description": "Invalid request. Codes: `invalid_json`, `unknown_field`, `unknown_source`, `missing_parameter`, `invalid_value`, `source_not_determined`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Codes: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/records/{id}": { "get": { "tags": [ "Records" ], "operationId": "getRecord", "summary": "Read one record live from its source", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Source-prefixed id.", "examples": { "ctgov": { "value": "ctgov:NCT07539311" }, "openfda": { "value": "openfda:enforcement:D-0082-2027" }, "fedreg": { "value": "fedreg:2026-22396" }, "edgar": { "value": "edgar:0001104659-26-120212" } } }, { "name": "max_age_hours", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 24, "default": 1 }, "description": "Oldest cached upstream response to accept; 0 forces a live read." } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResponse" } } } }, "400": { "description": "Invalid id or parameter. Codes: `invalid_id`, `unknown_field`, `invalid_value`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record. Codes: `record_not_found`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited. Codes: `rate_limit_exceeded`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The source failed or timed out. Codes: `upstream_error`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The source is not enabled. Codes: `source_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/watches": { "post": { "tags": [ "Early access" ], "operationId": "createWatch", "summary": "Save a query to be watched (stored; early access, not yet running)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 500 }, "webhook_url": { "type": "string", "format": "uri", "description": "https only." }, "email": { "type": "string", "format": "email" }, "website": { "type": "string", "description": "Honeypot. Leave empty." } }, "description": "Send `webhook_url` or `email` (at least one)." } } } }, "responses": { "202": { "description": "Stored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "id": { "type": "string" }, "status": { "const": "stored" }, "message": { "type": "string" }, "interpreted": { "$ref": "#/components/schemas/Interpreted" }, "warnings": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request. Codes: `invalid_json`, `unknown_field`, `missing_parameter`, `invalid_value`, `source_not_determined`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable. Codes: `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/early-access": { "post": { "tags": [ "Early access" ], "operationId": "requestEarlyAccess", "summary": "Request early access", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "company": { "type": "string", "maxLength": 200 }, "dataset_wanted": { "type": "string", "maxLength": 500 }, "use_case": { "type": "string", "maxLength": 2000 }, "website": { "type": "string", "description": "Honeypot. Leave empty." } } } } } }, "responses": { "201": { "description": "Received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "ok": { "const": true }, "id": { "type": "string" }, "status": { "const": "received" } } } } } }, "400": { "description": "Invalid request. Codes: `invalid_json`, `unknown_field`, `missing_parameter`, `invalid_value`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Storage unavailable. Codes: `storage_unavailable`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/presets": { "get": { "tags": [ "Meta" ], "operationId": "listPresets", "summary": "Example questions", "responses": { "200": { "description": "Presets.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "query": { "type": "string" } }, "required": [ "id", "label", "query" ] } } } } } } } }, "/v1/sources": { "get": { "tags": [ "Meta" ], "operationId": "listSources", "summary": "Registered sources, their filters, fields and live data timestamps", "description": "`source_updated_at` is read live from each source and cached for 10 minutes: ClinicalTrials.gov `/api/v2/version` dataTimestamp, openFDA `meta.last_updated`, and the Federal Register's newest publication_date. It is null when the source publishes none (SEC EDGAR) or the read failed.", "responses": { "200": { "description": "Sources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "live" ] }, "kinds": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object" }, "fields": { "type": "array", "items": { "type": "string" } }, "source_updated_at": { "type": [ "string", "null" ] }, "homepage": { "type": "string", "format": "uri" }, "description": { "type": "string" } }, "required": [ "id", "name", "status", "kinds", "filters", "source_updated_at", "homepage" ] } }, "early_access": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/llms.txt": { "get": { "tags": [ "Meta" ], "operationId": "llmsTxt", "summary": "Agent-facing summary of the API", "responses": { "200": { "description": "Plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "tags": [ "Meta" ], "operationId": "openapi", "summary": "This document", "responses": { "200": { "description": "OpenAPI 3.1.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "SearchRequest": { "type": "object", "additionalProperties": false, "description": "Either `query` (optionally with `source` as a hint) or `source` + `filters`. Unknown fields return 400 `unknown_field`.", "properties": { "query": { "type": "string", "maxLength": 500, "description": "Natural-language question." }, "source": { "type": "string", "enum": [ "ctgov", "openfda", "fedreg", "edgar" ], "description": "With `filters`: the source to query. With `query`: a hint that forces the source." }, "filters": { "description": "Exact filters for `source`. See `Filters.`.", "oneOf": [ { "$ref": "#/components/schemas/Filters.ctgov" }, { "$ref": "#/components/schemas/Filters.openfda" }, { "$ref": "#/components/schemas/Filters.fedreg" }, { "$ref": "#/components/schemas/Filters.edgar" } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Keep only these `record.fields` keys (see `Fields.`)." }, "cursor": { "type": "string", "description": "`next_cursor` from a previous response with the same query." }, "max_age_hours": { "type": "number", "minimum": 0, "maximum": 24, "default": 1, "description": "Oldest cached upstream response to accept; 0 forces a live read." } } }, "Filters.ctgov": { "type": "object", "additionalProperties": false, "description": "Filters for source `ctgov`. Any other key returns 400 `unknown_filter`.", "properties": { "condition": { "description": "Condition or disease (ClinicalTrials.gov expands synonyms)", "type": "string", "maxLength": 200 }, "term": { "description": "Free-text term across the study record", "type": "string", "maxLength": 200 }, "intervention": { "description": "Drug, device or procedure name", "type": "string", "maxLength": 200 }, "sponsor": { "description": "Lead sponsor or collaborator", "type": "string", "maxLength": 200 }, "phase": { "description": "Study phase(s). One value or an array of up to 10; case-insensitive.", "oneOf": [ { "type": "string", "enum": [ "EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4", "NA" ] }, { "type": "array", "items": { "type": "string", "enum": [ "EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4", "NA" ] }, "minItems": 1, "maxItems": 10 } ] }, "status": { "description": "Overall recruitment status. One value or an array of up to 10; case-insensitive.", "oneOf": [ { "type": "string", "enum": [ "RECRUITING", "NOT_YET_RECRUITING", "ACTIVE_NOT_RECRUITING", "ENROLLING_BY_INVITATION", "COMPLETED", "SUSPENDED", "TERMINATED", "WITHDRAWN" ] }, { "type": "array", "items": { "type": "string", "enum": [ "RECRUITING", "NOT_YET_RECRUITING", "ACTIVE_NOT_RECRUITING", "ENROLLING_BY_INVITATION", "COMPLETED", "SUSPENDED", "TERMINATED", "WITHDRAWN" ] }, "minItems": 1, "maxItems": 10 } ] }, "updated_since": { "description": "Last update posted on or after (YYYY-MM-DD)", "type": "string", "format": "date", "examples": [ "2026-10-05" ] }, "updated_until": { "description": "Last update posted on or before (YYYY-MM-DD)", "type": "string", "format": "date", "examples": [ "2026-10-05" ] } } }, "Filters.openfda": { "type": "object", "additionalProperties": false, "description": "Filters for source `openfda`. Any other key returns 400 `unknown_filter`.", "properties": { "category": { "description": "drug, device or food (default drug). Case-insensitive; returned in canonical form.", "type": "string", "enum": [ "drug", "device", "food" ] }, "classification": { "description": "Recall class (Class I is most serious). Case-insensitive; returned in canonical form.", "type": "string", "enum": [ "Class I", "Class II", "Class III" ] }, "status": { "description": "Recall status. Case-insensitive; returned in canonical form.", "type": "string", "enum": [ "Ongoing", "Completed", "Terminated" ] }, "firm": { "description": "Recalling firm name", "type": "string", "maxLength": 200 }, "term": { "description": "Phrase in product description or reason for recall", "type": "string", "maxLength": 200 }, "reported_since": { "description": "Enforcement report date on or after (YYYY-MM-DD)", "type": "string", "format": "date", "examples": [ "2026-10-05" ] }, "reported_until": { "description": "Enforcement report date on or before (YYYY-MM-DD)", "type": "string", "format": "date", "examples": [ "2026-10-05" ] } } }, "Filters.fedreg": { "type": "object", "additionalProperties": false, "description": "Filters for source `fedreg`. Any other key returns 400 `unknown_filter`.", "properties": { "term": { "description": "Full-text term; quote phrases, e.g. \"data center\"", "type": "string", "maxLength": 200 }, "agencies": { "description": "Agency slugs, e.g. environmental-protection-agency. One value or an array of up to 10.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 10 } ] }, "type": { "description": "Document type(s). One value or an array of up to 10; case-insensitive.", "oneOf": [ { "type": "string", "enum": [ "RULE", "PRORULE", "NOTICE", "PRESDOCU" ] }, { "type": "array", "items": { "type": "string", "enum": [ "RULE", "PRORULE", "NOTICE", "PRESDOCU" ] }, "minItems": 1, "maxItems": 10 } ] }, "published_since": { "description": "Published on or after (YYYY-MM-DD)", "type": "string", "format": "date", "examples": [ "2026-10-05" ] }, "published_until": { "description": "Published on or before (YYYY-MM-DD)", "type": "string", "format": "date", "examples": [ "2026-10-05" ] } } }, "Filters.edgar": { "type": "object", "additionalProperties": false, "description": "Filters for source `edgar`. Any other key returns 400 `unknown_filter`.", "properties": { "term": { "description": "Full-text term; quote phrases, e.g. \"interconnection agreement\"", "type": "string", "maxLength": 200 }, "forms": { "description": "Form types, e.g. 8-K. One value or an array of up to 10; case-insensitive.", "oneOf": [ { "type": "string", "enum": [ "8-K", "10-K", "10-Q", "S-1", "6-K", "20-F", "DEF 14A", "SC 13D", "SC 13G", "4", "424B4" ] }, { "type": "array", "items": { "type": "string", "enum": [ "8-K", "10-K", "10-Q", "S-1", "6-K", "20-F", "DEF 14A", "SC 13D", "SC 13G", "4", "424B4" ] }, "minItems": 1, "maxItems": 10 } ] }, "filed_since": { "description": "Filed on or after (YYYY-MM-DD)", "type": "string", "format": "date", "examples": [ "2026-10-05" ] }, "filed_until": { "description": "Filed on or before (YYYY-MM-DD)", "type": "string", "format": "date", "examples": [ "2026-10-05" ] } } }, "Interpreted": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "ctgov", "openfda", "fedreg", "edgar", "iso_queue", "shopping" ], "description": "`iso_queue` (ISO/RTO interconnection queues) and `shopping` (product listings and live prices) are recognised questions in early access: no query is run and a notice explains." }, "filters": { "type": "object", "description": "The validated filters that were run." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "One note per interpretation step, e.g. \"'last 30 days' read as updated_since 2026-10-05\"." }, "upstream": { "type": "array", "description": "Search responses only. The exact public upstream request behind `total` (no keys), so a client can re-run it and compare the source's own count. ClinicalTrials.gov, openFDA and the Federal Register allow browser (CORS) requests; SEC EDGAR does not. When our `total` differs from the source's (EDGAR groups documents into filings), a notice says why.", "items": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "total_path": { "type": "string", "description": "JSON path to the source's total: `totalCount` (ctgov), `meta.results.total` (openfda), `count` (fedreg), `hits.total.value` (edgar)." } }, "required": [ "source", "url", "total_path" ] } } }, "required": [ "source", "filters", "notes" ] }, "SearchResponse": { "type": "object", "properties": { "request_id": { "type": "string" }, "interpreted": { "$ref": "#/components/schemas/Interpreted" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Record" } }, "total": { "type": [ "integer", "null" ], "description": "Matches at the source; null when the source can't say (EDGAR counts documents, not filings)." }, "next_cursor": { "type": [ "string", "null" ] }, "notices": { "type": "array", "items": { "type": "string" }, "description": "Caveats written for the model to read." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Problems written for the developer, e.g. a source that failed." }, "usage": { "$ref": "#/components/schemas/Usage" }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "cost": { "$ref": "#/components/schemas/Cost" }, "timing_ms": { "type": "integer" } }, "required": [ "request_id", "interpreted", "results", "total", "next_cursor", "notices", "warnings", "usage", "freshness", "cost", "timing_ms" ] }, "RecordResponse": { "type": "object", "properties": { "request_id": { "type": "string" }, "record": { "$ref": "#/components/schemas/Record" }, "notices": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "usage": { "$ref": "#/components/schemas/Usage" }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "cost": { "$ref": "#/components/schemas/Cost" }, "timing_ms": { "type": "integer" } } }, "Usage": { "type": "object", "properties": { "records": { "type": "integer", "description": "Records in this response." }, "response_bytes": { "type": "integer", "description": "Size of this response body in bytes." }, "source_bytes": { "type": "integer", "description": "Raw upstream JSON bytes read to build it (original size on a cache hit). For ctgov, the full study records." }, "source_requests": { "type": "integer", "description": "Upstream reads needed, whether served live or from cache." } }, "required": [ "records", "response_bytes", "source_bytes", "source_requests" ] }, "Freshness": { "type": "object", "properties": { "max_age_hours": { "type": "number" }, "served_from": { "type": "string", "enum": [ "live", "cache", "mixed" ] } }, "required": [ "max_age_hours", "served_from" ] }, "Cost": { "type": "object", "properties": { "usd": { "type": "number" } } }, "Record": { "type": "object", "description": "picabird.record@1", "properties": { "id": { "type": "string", "examples": [ "ctgov:NCT07539311" ] }, "schema": { "type": "string", "description": "Per-source schema version, e.g. `ctgov.study@1`." }, "kind": { "type": "string", "enum": [ "clinical_trial", "recall", "regulatory_document", "sec_filing" ] }, "title": { "type": [ "string", "null" ] }, "summary": { "type": "string", "description": "Built from fields by code, never by a model." }, "event": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "updated", "recalled", "published", "filed" ] }, "date": { "type": [ "string", "null" ], "format": "date" } } }, "fields": { "description": "Typed per source; see `Fields.`.", "oneOf": [ { "$ref": "#/components/schemas/Fields.ctgov" }, { "$ref": "#/components/schemas/Fields.openfda" }, { "$ref": "#/components/schemas/Fields.fedreg" }, { "$ref": "#/components/schemas/Fields.edgar" } ] }, "entities": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } } } }, "matched": { "type": "array", "items": { "type": "object", "properties": { "criterion": { "type": "string" }, "field": { "type": "string" }, "evidence": { "type": [ "string", "null" ], "description": "The text in the record that matched." }, "weak": { "type": "boolean", "description": "True when the source's index matched but the term is not in the title or abstract." }, "document": { "type": "string", "description": "EDGAR: URL of the matching document." } } } }, "provenance": { "$ref": "#/components/schemas/Provenance" } }, "required": [ "id", "schema", "kind", "title", "summary", "event", "fields", "entities", "matched", "provenance" ] }, "Fields.ctgov": { "type": "object", "description": "`record.fields` for source `ctgov`. Values are source facts; unknown values are null. `provenance.paths` maps each field to its path in the source record. Use these names in the request's `fields` projection.", "properties": { "phase": { "description": "ctgov field `phase`" }, "status": { "description": "ctgov field `status`" }, "study_type": { "description": "ctgov field `study_type`" }, "sponsor": { "description": "ctgov field `sponsor`" }, "conditions": { "description": "ctgov field `conditions`" }, "interventions": { "description": "ctgov field `interventions`" }, "primary_outcomes": { "description": "ctgov field `primary_outcomes`" }, "enrollment": { "description": "ctgov field `enrollment`" }, "start_date": { "description": "ctgov field `start_date`" }, "primary_completion_date": { "description": "ctgov field `primary_completion_date`" }, "last_update_posted": { "description": "ctgov field `last_update_posted`" }, "last_update_submitted": { "description": "ctgov field `last_update_submitted`" } } }, "Fields.openfda": { "type": "object", "description": "`record.fields` for source `openfda`. Values are source facts; unknown values are null. `provenance.paths` maps each field to its path in the source record. Use these names in the request's `fields` projection.", "properties": { "recall_number": { "description": "openfda field `recall_number`" }, "classification": { "description": "openfda field `classification`" }, "status": { "description": "openfda field `status`" }, "recalling_firm": { "description": "openfda field `recalling_firm`" }, "product_description": { "description": "openfda field `product_description`" }, "reason_for_recall": { "description": "openfda field `reason_for_recall`" }, "product_quantity": { "description": "openfda field `product_quantity`" }, "distribution_pattern": { "description": "openfda field `distribution_pattern`" }, "voluntary_mandated": { "description": "openfda field `voluntary_mandated`" }, "recall_initiation_date": { "description": "openfda field `recall_initiation_date`" }, "center_classification_date": { "description": "openfda field `center_classification_date`" }, "report_date": { "description": "openfda field `report_date`" }, "termination_date": { "description": "openfda field `termination_date`" }, "brand_names": { "description": "openfda field `brand_names`" }, "event_id": { "description": "openfda field `event_id`" }, "category": { "description": "openfda field `category`" }, "location": { "description": "openfda field `location`" } } }, "Fields.fedreg": { "type": "object", "description": "`record.fields` for source `fedreg`. Values are source facts; unknown values are null. `provenance.paths` maps each field to its path in the source record. Use these names in the request's `fields` projection.", "properties": { "document_number": { "description": "fedreg field `document_number`" }, "document_type": { "description": "fedreg field `document_type`" }, "action": { "description": "fedreg field `action`" }, "agencies": { "description": "fedreg field `agencies`" }, "abstract": { "description": "fedreg field `abstract`" }, "publication_date": { "description": "fedreg field `publication_date`" }, "comments_close_on": { "description": "fedreg field `comments_close_on`" }, "effective_on": { "description": "fedreg field `effective_on`" }, "docket_ids": { "description": "fedreg field `docket_ids`" }, "regulation_id_numbers": { "description": "fedreg field `regulation_id_numbers`" }, "significant": { "description": "fedreg field `significant`" }, "pdf_url": { "description": "fedreg field `pdf_url`" } } }, "Fields.edgar": { "type": "object", "description": "`record.fields` for source `edgar`. Values are source facts; unknown values are null. `provenance.paths` maps each field to its path in the source record. Use these names in the request's `fields` projection.", "properties": { "accession_number": { "description": "edgar field `accession_number`" }, "cik": { "description": "edgar field `cik`" }, "form": { "description": "edgar field `form`" }, "file_date": { "description": "edgar field `file_date`" }, "period_ending": { "description": "edgar field `period_ending`" }, "items": { "description": "edgar field `items`" }, "business_location": { "description": "edgar field `business_location`" }, "sic": { "description": "edgar field `sic`" }, "company": { "description": "edgar field `company`" }, "tickers": { "description": "edgar field `tickers`" }, "item_descriptions": { "description": "edgar field `item_descriptions`" }, "matched_documents": { "description": "edgar field `matched_documents`" } } }, "Provenance": { "type": "object", "properties": { "source": { "type": "string" }, "url": { "type": [ "string", "null" ], "description": "Human-readable page at the source." }, "api_url": { "type": "string" }, "retrieved_at": { "type": "string", "format": "date-time", "description": "When we fetched it from the source (the original time on a cache hit)." }, "source_updated_at": { "type": [ "string", "null" ], "description": "The source's own data timestamp, when it publishes one." }, "cache": { "type": "string", "enum": [ "live", "cached" ] }, "paths": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Record key (`title`, `event.date`, `fields.`) → path in the JSON that `api_url` returns, starting at `api_root`. Syntax: dot-separated keys, `[n]` for an index, `[]` to map over an array (e.g. `agencies[].name`). Dates in the source may be `YYYYMMDD` (openFDA); records give ISO 8601." }, "api_root": { "type": [ "string", "null" ], "description": "Where the record's object sits in the `api_url` response: null for the root (ctgov, fedreg), `results[0]` (openfda), `hits.hits[0]._source` (edgar)." }, "derived": { "type": "array", "items": { "type": "string" }, "description": "Record keys computed by Picabird with no single source path, e.g. `fields.category` (openFDA endpoint) or `title` when shortened." }, "terms": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" } }, "required": [ "source", "url", "api_url", "retrieved_at", "source_updated_at", "cache", "paths", "api_root", "derived", "terms" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request", "not_found", "rate_limited", "upstream_unavailable", "api_error" ] }, "code": { "type": "string", "enum": [ "invalid_json", "unknown_field", "unknown_filter", "unknown_source", "missing_parameter", "missing_filter", "conflicting_parameters", "invalid_value", "invalid_cursor", "invalid_id", "source_not_determined", "method_not_allowed", "endpoint_not_found", "record_not_found", "rate_limit_exceeded", "upstream_error", "source_unavailable", "storage_unavailable", "internal_error" ] }, "message": { "type": "string" }, "param": { "type": "string", "description": "The request field at fault, e.g. `filters.phase`." } }, "required": [ "type", "code", "message" ] }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ] } } } }