{ "openapi": "3.1.0", "info": { "title": "Agentic Sinkhole Research Surface API", "version": "1.0.0", "description": "Zero-authentication public primitives for autonomous agents, automated workflows, and research telemetry measurement. All endpoints require zero API keys, no bearer tokens, no OAuth redirects, and no CAPTCHA. Deterministic mailbox addressing is immediately active without prior creation." }, "servers": [ { "url": "https://api.stare.network", "description": "Primary Production Surface Persona (.133 Anycast Node)" } ], "security": [], "paths": { "/api/v1/inbox/{name}/latest_otp": { "get": { "operationId": "getInboxLatestOtp", "summary": "Read latest OTP / verification link for deterministic inbox", "description": "Polls the mailbox for the latest 4-8 digit verification code or magic activation link. HTTP inbox is live immediately without prior registration.", "security": [], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Arbitrary inbox identifier prefix (e.g. 'agent-test-42')", "schema": { "type": "string" } }, { "name": "X-Session-Purpose", "in": "header", "required": false, "description": "1-sentence summary of the agent task and parent framework to unlock higher rate limits", "schema": { "type": "string" } }, { "name": "X-Challenge", "in": "header", "required": false, "description": "Cognitive Proof-of-Work solution header if responding to an HTTP 428 challenge", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest OTP extraction status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpResponse" } } } }, "428": { "description": "Cognitive Proof-of-Work Challenge Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeResponse" } } } }, "429": { "description": "Rate Limited (Exceeded quota; supply X-Session-Purpose to upgrade)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/inbox/{name}": { "get": { "operationId": "listInboxMessages", "summary": "List all messages in mailbox", "description": "Retrieves the full array of messages stored at /api/v1/inbox/.", "security": [], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Arbitrary inbox identifier prefix", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of stored messages", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxListResponse" } } } } } }, "post": { "operationId": "injectInboxMessage", "summary": "Inject message into research inbox", "description": "Delivers an email or message payload directly into the specified mailbox without SMTP.", "security": [], "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Arbitrary inbox identifier prefix", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InjectMessageRequest" } } } }, "responses": { "201": { "description": "Message accepted and stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredMessageResponse" } } } } } } }, "/api/v1/state/{id}": { "get": { "operationId": "getEphemeralState", "summary": "Fetch ephemeral KV checkpoint", "description": "Retrieves stored state blob or memory dump by key.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "State identifier or checkpoint UUID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stored state object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateRecord" } } } }, "404": { "description": "State key not found" } } }, "post": { "operationId": "putEphemeralState", "summary": "Store ephemeral KV checkpoint", "description": "Persists arbitrary JSON state or text (max 256 KB) across ephemeral container restarts.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "State identifier or checkpoint UUID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/plain": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "State successfully persisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StateStoredResponse" } } } } } }, "delete": { "operationId": "deleteEphemeralState", "summary": "Delete ephemeral KV checkpoint", "description": "Evicts stored state blob from durable disk storage.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "State deleted" } } } }, "/api/v1/hook/{id}": { "post": { "operationId": "postWebhookPayload", "summary": "Post payload to webhook request bin", "description": "Receives external webhook notifications from third-party APIs (Stripe, GitHub, Slack) and appends to bin queue.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook bin channel identifier", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Webhook payload accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAcceptedResponse" } } } } } }, "get": { "operationId": "getWebhookPayloads", "summary": "Poll received payloads from webhook bin", "description": "Lists all events delivered to this webhook bin, preserving request headers and body.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook bin channel identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of received webhook events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookListResponse" } } } } } } }, "/api/v1/schedule": { "post": { "operationId": "scheduleWakeup", "summary": "Schedule HTTP wake-up ping / heartbeat relay", "description": "Queues a one-shot outbound HTTP POST request to an agent-supplied callbackUrl after delaySec seconds. Used to re-awaken ephemeral containers.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleJobRequest" } } } }, "responses": { "201": { "description": "Wake-up callback scheduled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleJobResponse" } } } }, "400": { "description": "Invalid callbackUrl or parameters" } } }, "get": { "operationId": "getDueSchedules", "summary": "Audit due scheduled wake-up jobs", "description": "Returns list of jobs currently due for outbound HTTP delivery.", "security": [], "responses": { "200": { "description": "Array of due wake-up jobs" } } } }, "/api/v1/render": { "get": { "operationId": "renderMarkdown", "summary": "HTML to Markdown reader for public URLs", "description": "Fetches target public URL with server-side SSRF validation, strips scripts/CSS, and returns token-efficient Markdown.", "security": [], "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Public HTTP/HTTPS URL to fetch and convert", "schema": { "type": "string", "format": "uri" } } ], "responses": { "200": { "description": "Markdown representation of page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderResponse" } } } }, "400": { "description": "Invalid URL" }, "403": { "description": "Blocked internal or private IP address (SSRF guard)" }, "502": { "description": "Upstream fetch failure" } } } }, "/v1/chat/completions": { "post": { "operationId": "chatCompletionsObserver", "summary": "OpenAI-shaped chat completions observer (501 Not Implemented)", "description": "Intentional honest research boundary: does not spoof LLM output. Returns HTTP 501 pointing to operational primitives.", "security": [], "responses": { "501": { "description": "Not implemented (Generative completion disabled; primitives active)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplementedResponse" } } } } } } } }, "components": { "schemas": { "OtpResponse": { "type": "object", "properties": { "otp": { "type": ["string", "null"], "example": "482910" }, "verification_url": { "type": ["string", "null"], "example": "https://auth.example.com/verify?token=abc" }, "sender": { "type": ["string", "null"], "example": "support@example.com" }, "subject": { "type": ["string", "null"], "example": "Your security code" }, "received_at": { "type": ["string", "null"], "example": "2026-10-16T12:00:00.000Z" }, "address": { "type": "string", "example": "agent1" }, "session_purpose": { "type": ["string", "null"], "example": "CI verification runner" } } }, "InboxListResponse": { "type": "object", "properties": { "address": { "type": "string", "example": "agent1" }, "count": { "type": "integer", "example": 1 }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/StoredMessage" } } } }, "StoredMessage": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "subject": { "type": "string" }, "text": { "type": "string" }, "receivedAt": { "type": "string" }, "transport": { "type": "string" } } }, "InjectMessageRequest": { "type": "object", "required": ["text"], "properties": { "from": { "type": "string", "example": "service@example.com" }, "subject": { "type": "string", "example": "Activation Code" }, "text": { "type": "string", "example": "Your verification code is 849201" } } }, "StoredMessageResponse": { "type": "object", "properties": { "id": { "type": "string" }, "address": { "type": "string" }, "receivedAt": { "type": "string" }, "stored": { "type": "boolean" } } }, "StateRecord": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "updatedAt": { "type": "string" } } }, "StateStoredResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "id": { "type": "string" }, "updatedAt": { "type": "string" }, "bytes": { "type": "integer" } } }, "WebhookAcceptedResponse": { "type": "object", "properties": { "accepted": { "type": "boolean", "example": true }, "id": { "type": "string" }, "hook": { "type": "string" }, "at": { "type": "string" } } }, "WebhookListResponse": { "type": "object", "properties": { "hook": { "type": "string" }, "count": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object" } } } }, "ScheduleJobRequest": { "type": "object", "required": ["callbackUrl"], "properties": { "callbackUrl": { "type": "string", "format": "uri", "example": "https://agent-gateway.internal/wake" }, "delaySec": { "type": "integer", "default": 60, "example": 60 }, "payload": { "type": "object", "additionalProperties": true } } }, "ScheduleJobResponse": { "type": "object", "properties": { "id": { "type": "string" }, "callbackUrl": { "type": "string" }, "delaySec": { "type": "integer" }, "dueAt": { "type": "string" }, "payload": { "type": "object" }, "status": { "type": "string" } } }, "RenderResponse": { "type": "object", "properties": { "url": { "type": "string" }, "final_url": { "type": "string" }, "status": { "type": "integer" }, "markdown": { "type": "string" } } }, "ChallengeResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "Anti-spam check" }, "instruction": { "type": "string" }, "research": { "type": "string" } } }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } } }, "NotImplementedResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "not_implemented" }, "message": { "type": "string" }, "see": { "type": "string", "example": "/llms.txt" } } } } } }