{ "openapi": "3.1.0", "info": { "title": "OrgAInism Machine API", "version": "1.0.0", "summary": "Reconciled living records of real businesses, for AI agents.", "description": "Every entity carries a declared stream (self-reported), an observed stream (crawled, registry-checked) and an experienced stream (what happened on contact). Responses expose the reconciliation, with agreement markers, trust score and a vitality heartbeat. THE SERVING GATE: you will never receive a dead link from this organism — records are quarantined from circulation the moment the heartbeat stops, and only status=active records appear in search, referrals and recommendations. Out-of-circulation records stay readable at their direct endpoint with a serving.status block (transparency, not erasure); pass include=archived to request them. Natural death is quarantined then archived and restores automatically; deception is blacklisted with trust floored to 0 and an expensive re-entry path. Reads are open; ingest is authenticated.", "license": { "name": "Citation License 1.0", "url": "https://bestexpertanswers.com/license" } }, "servers": [ { "url": "https://q-and-a.ai" } ], "tags": [ { "name": "entities", "description": "Read reconciled records" }, { "name": "converse", "description": "Ask the entity directly" }, { "name": "changes", "description": "Delta feed — sync once, sip diffs forever" }, { "name": "ingest", "description": "Worker-only observation writes" }, { "name": "crawl-tasks", "description": "Worker-only queue of data gaps to fill" }, { "name": "observe", "description": "Open field reports — tell the organism it is wrong" }, { "name": "federation", "description": "Badges and record signature verification" }, { "name": "experience", "description": "The experienced stream — what actually happened" }, { "name": "lifecycle", "description": "The serving gate: quarantine, grace window, archive, blacklist, restoration and coverage grants" } ], "paths": { "/api/public/entity": { "get": { "tags": [ "entities" ], "operationId": "getEntity", "summary": "Full reconciled record for one entity", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reconciled record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityPayload" } } } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/api/public/entities": { "get": { "tags": [ "entities" ], "operationId": "searchEntities", "summary": "Search the organism", "parameters": [ { "name": "trade", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "vitality", "in": "query", "schema": { "type": "string", "enum": [ "alive", "dormant", "unverified", "divergent" ] } }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 25 } }, { "name": "offset", "in": "query", "description": "Page through the full set. The response carries next_offset and next_url while more records remain.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "include", "in": "query", "description": "Serving gate opt-out. By default only in-circulation (status=active) records are returned. Use include=archived to also receive quarantined, archived and blacklisted records.", "schema": { "type": "string", "enum": [ "archived", "all" ] } } ], "responses": { "200": { "description": "Matching entities", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "entities": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySummary" } } } } } } } } } }, "/api/public/converse": { "post": { "tags": [ "converse" ], "operationId": "converse", "summary": "Ask the entity a question; it answers in the first person", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_id", "message" ], "properties": { "entity_id": { "type": "string", "format": "uuid" }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "history": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "The entity's answer", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string" }, "entity_id": { "type": "string", "format": "uuid" }, "entity_name": { "type": "string" }, "revision": { "type": "integer" }, "trust_score": { "type": "integer" }, "vitality": { "$ref": "#/components/schemas/Vitality" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": [ "string", "null" ] }, "stream": { "type": "string", "enum": [ "declared", "observed" ] }, "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } } }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/api/public/changes": { "get": { "tags": [ "changes" ], "operationId": "getChanges", "summary": "Global change delta feed — never crawl us twice", "description": "Every ingest, declaration and reconciliation appends one row to a global monotonically increasing sequence. Full-sync once, store latest_seq, then poll with since=latest_seq.", "parameters": [ { "name": "since", "in": "query", "description": "Return changes with seq greater than this value.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 } } ], "responses": { "200": { "description": "Changes after the given sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "latest_seq": { "type": "integer" }, "has_more": { "type": "boolean" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeEvent" } } } } } } }, "400": { "$ref": "#/components/responses/Error" } } } }, "/api/public/ingest": { "post": { "tags": [ "ingest" ], "operationId": "ingest", "summary": "Append observations (worker operators only)", "security": [ { "ingestKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "observations" ], "properties": { "observations": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ObservationInput" } } } } } } }, "responses": { "200": { "description": "Ingest result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ingested": { "type": "integer" }, "entities": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/public/crawl-tasks": { "get": { "tags": [ "crawl-tasks" ], "operationId": "listCrawlTasks", "summary": "Deduped, count-ranked data gaps (worker operators only)", "security": [ { "ingestKey": [] } ], "responses": { "200": { "description": "Task queue", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/CrawlTask" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "crawl-tasks" ], "operationId": "resolveCrawlTasks", "summary": "Mark tasks resolved", "security": [ { "ingestKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resolve" ], "properties": { "resolve": { "type": "array", "minItems": 1, "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Resolution result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "resolved": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" } } } }, "/api/public/observe": { "post": { "tags": [ "observe" ], "operationId": "submitFieldReport", "summary": "Report a field you experienced differently (open, rate-limited per IP)", "description": "If you found the record wrong, tell the organism — you are part of it. Reports enter quarantine and are never written straight to canonical data. A report is promoted into the observed stream (source field_report, visible in /api/public/changes) after 3+ independent reporters agree on the same value, or when an operator approves it. Reporter reputation is tracked.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_id", "field", "reported_value" ], "properties": { "entity_id": { "type": "string", "format": "uuid" }, "field": { "type": "string", "maxLength": 80 }, "reported_value": { "type": "string", "maxLength": 500 }, "evidence_note": { "type": "string", "maxLength": 1000 }, "reporter": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "Report accepted into quarantine", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "quarantined", "promoted" ] }, "corroborations": { "type": "integer" }, "needed": { "type": "integer" }, "reporter_reputation": { "type": "object", "properties": { "submitted": { "type": "integer" }, "confirmed": { "type": "integer" }, "rejected": { "type": "integer" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/api/public/badge": { "get": { "tags": [ "federation" ], "operationId": "getBadge", "summary": "Embeddable JavaScript vitality badge for a claimed entity", "description": "Returns JavaScript that renders a live vitality badge linking back to the canonical record. Each render is logged as a demand event (kind badge_view).", "parameters": [ { "name": "entity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Badge script", "content": { "application/javascript": { "schema": { "type": "string" } } } } } } }, "/api/public/verify": { "get": { "tags": [ "federation" ], "operationId": "verifyRecordSignature", "summary": "Verify a record signature you cached earlier", "description": "Every entity response carries a signature block (alg, key_id, signed_at, sig) over the canonical record JSON. Phase 1 is HMAC-SHA256 with a server secret; phase 2 upgrades to asymmetric keys / DID for offline verification.", "parameters": [ { "name": "entity_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sig", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "key_id": { "type": "string" }, "current_revision": { "type": "integer" }, "signed_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/api/public/experience": { "post": { "tags": [ "experience" ], "operationId": "pushExperiences", "summary": "Write to the experienced stream (call-tracking providers only)", "description": "Reserved for a call-tracking provider (TODO: CALL_TRACKING_PROVIDER). Experience rows appear as experienced[] on the record, carry 15 points of the trust score, and are written to the delta feed with stream experienced.", "security": [ { "ingestKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "experiences" ], "properties": { "experiences": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "entity_id", "kind" ], "properties": { "entity_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "call_answered", "call_missed", "call_duration", "repeat_contact", "job_outcome" ] }, "value": { "type": "string" }, "source": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" } } } } } } } } }, "responses": { "200": { "description": "Ingest result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "written": { "type": "integer" }, "entities_touched": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "ingestKey": { "type": "http", "scheme": "bearer", "description": "Bearer token equal to the server's INGEST_API_KEY secret." } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "schemas": { "Vitality": { "type": "string", "enum": [ "alive", "dormant", "unverified", "divergent" ], "description": "Heartbeat of the record." }, "Agreement": { "type": "string", "enum": [ "agree", "divergent", "declared_only", "observed_only" ], "description": "How the two truth streams relate for this field." }, "EntitySummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "trade": { "type": "string" }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "license_number": { "type": [ "string", "null" ] }, "license_status": { "type": [ "string", "null" ] }, "trust_score": { "type": "integer" }, "vitality": { "$ref": "#/components/schemas/Vitality" }, "claimed": { "type": "boolean" }, "last_declared_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/ServingStatus" }, "status_reason": { "type": [ "string", "null" ] }, "served_areas": { "type": "array", "items": { "type": "string" } }, "serves_via_grant": { "type": [ "string", "null" ], "description": "Present when this entity is in these results because a coverage grant gave it the queried city. Label it as 'serves {city} · located {home_city}'." } } }, "ServingStatus": { "type": "string", "enum": [ "active", "quarantined", "archived", "blacklisted" ], "description": "Only 'active' records are in circulation (search, referrals, related entities, converse recommendations)." }, "Serving": { "type": "object", "description": "The serving gate block. Quarantined/archived = died (free, automatic restoration). Blacklisted = lied (trust 0, badge deactivated, re-entry requires registry-phone re-verification plus operator approval).", "properties": { "status": { "$ref": "#/components/schemas/ServingStatus" }, "in_circulation": { "type": "boolean" }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": [ "string", "null" ], "format": "date-time" }, "recheck_count": { "type": "integer" }, "max_rechecks": { "type": "integer" }, "recheck_after": { "type": [ "string", "null" ], "format": "date-time" }, "died_at": { "type": [ "string", "null" ], "format": "date-time" }, "blacklist_tier": { "type": [ "string", "null" ] }, "reentry_status": { "type": [ "string", "null" ] }, "notice": { "type": "string" } } }, "CoverageGrant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "city": { "type": "string" }, "state": { "type": "string" }, "source": { "type": "string", "enum": [ "coverage_grant" ] }, "reason": { "type": [ "string", "null" ] }, "vacated_entity": { "type": [ "string", "null" ], "format": "uuid" }, "granted_at": { "type": "string", "format": "date-time" } } }, "ReconciledField": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "value": { "type": [ "string", "null" ] }, "agreement": { "$ref": "#/components/schemas/Agreement" }, "declared_value": { "type": [ "string", "null" ] }, "observed_value": { "type": [ "string", "null" ] }, "declared_at": { "type": [ "string", "null" ], "format": "date-time" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] } } }, "EntityPayload": { "type": "object", "properties": { "entity": { "$ref": "#/components/schemas/EntitySummary" }, "reconciled_fields": { "type": "array", "items": { "$ref": "#/components/schemas/ReconciledField" } }, "divergences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "field": { "type": "string" }, "declared_value": { "type": [ "string", "null" ] }, "observed_value": { "type": [ "string", "null" ] }, "status": { "type": "string" } } } }, "trust_score": { "type": "integer" }, "vitality": { "$ref": "#/components/schemas/Vitality" }, "revision": { "type": "integer" }, "serving": { "$ref": "#/components/schemas/Serving" }, "served_areas": { "type": "array", "items": { "type": "string" } }, "coverage_grants": { "type": "array", "items": { "$ref": "#/components/schemas/CoverageGrant" } }, "license_notice": { "type": "string" } } }, "ChangeEvent": { "type": "object", "properties": { "seq": { "type": "integer" }, "entity_id": { "type": "string", "format": "uuid" }, "entity_endpoint": { "type": "string", "format": "uri" }, "revision": { "type": "integer" }, "stream": { "type": "string", "enum": [ "declared", "observed", "reconciled" ] }, "change_type": { "type": "string", "enum": [ "added", "modified", "removed", "quarantined", "archived", "restored", "blacklisted" ] }, "fields_changed": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "CrawlTask": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "entity_gap", "coverage_gap" ] }, "entity_id": { "type": [ "string", "null" ], "format": "uuid" }, "query": { "type": [ "string", "null" ] }, "trade": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "last_seen": { "type": "string", "format": "date-time" } } }, "ObservationInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "trade": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "website": { "type": "string" }, "license_number": { "type": "string" }, "license_status": { "type": "string" }, "source": { "type": "string" }, "source_url": { "type": "string" }, "liveness": { "type": "object", "additionalProperties": { "type": "string" } }, "fields": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }