{ "openapi": "3.1.0", "info": { "title": "Precision Mito Research Services", "version": "1.0.0", "description": "Four research services. 3 successful requests per UTC month; up to 25 results per call. All account keys share allowance; anonymous users share a network allowance. No synthetic integration sandbox. Read the guide for source, coverage and scientific limitations.", "contact": { "email": "support@precisionmito.com" } }, "servers": [ { "url": "https://precisionmito.com/api/agent-research/v1" } ], "externalDocs": { "url": "https://precisionmito.com/agent-research-api.txt" }, "paths": { "/papers": { "get": { "operationId": "research_papers", "summary": "Find public-library paper metadata", "description": "One request on success, including empty results. Shared allowance: 3/month (UTC); prepaid thereafter. Original-source terms apply. Research discovery, not medical advice.", "security": [ {}, { "researchApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Title/journal/PMID text for papers; directory text for researchers; card text for evidence cards.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Results per request.", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset pagination; use cursor instead for changes.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/changes": { "get": { "operationId": "research_changes", "summary": "Page new or updated paper metadata since a UTC timestamp", "description": "One request on success, including empty results. Shared allowance: 3/month (UTC); prepaid thereafter. Original-source terms apply. Research discovery, not medical advice.", "security": [ {}, { "researchApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Title/journal/PMID text for papers; directory text for researchers; card text for evidence cards.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Results per request.", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }, { "name": "since", "in": "query", "required": true, "description": "Required UTC timestamp ending in Z; keep unchanged across pages.", "schema": { "type": "string", "format": "date-time" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the prior page. Keep since and q unchanged.", "schema": { "type": "string", "maxLength": 1500 } } ], "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/researchers": { "get": { "operationId": "research_researchers", "summary": "Find public researcher profiles without contact data", "description": "One request on success, including empty results. Shared allowance: 3/month (UTC); prepaid thereafter. Original-source terms apply. Research discovery, not medical advice.", "security": [ {}, { "researchApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Title/journal/PMID text for papers; directory text for researchers; card text for evidence cards.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Results per request.", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset pagination; use cursor instead for changes.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/evidence-cards": { "get": { "operationId": "research_evidence_cards", "summary": "Read starter summaries or an explicitly metadata-only card", "description": "One request on success, including empty results. Shared allowance: 3/month (UTC); prepaid thereafter. Original-source terms apply. Research discovery, not medical advice.", "security": [ {}, { "researchApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Title/journal/PMID text for papers; directory text for researchers; card text for evidence cards.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "required": false, "description": "Results per request.", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }, { "name": "offset", "in": "query", "required": false, "description": "Offset pagination; use cursor instead for changes.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "pmid", "in": "query", "required": false, "description": "Request one PMID. Other library PMIDs can return metadata-only cards.", "schema": { "type": "string", "pattern": "^[0-9]{1,12}$" } } ], "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/config": { "get": { "operationId": "research_config", "summary": "Inspect prices, limits, starter coverage and checkout availability; no request credit spent", "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/usage": { "get": { "operationId": "research_usage", "summary": "Inspect network or key account balance; no request credit spent", "security": [ {}, { "researchApiKey": [] } ], "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/account": { "get": { "operationId": "research_account", "summary": "Existing signed-in browser: own keys, usage and orders", "security": [ { "browserSession": [] } ], "parameters": [ { "name": "session_id", "in": "query", "required": false, "description": "Optional Stripe Checkout session owned by the signed-in user.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/keys": { "post": { "operationId": "research_create_key", "summary": "Signed-in browser: create revocable account API key (secret shown once)", "security": [ { "browserSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 } } } } } }, "responses": { "201": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/keys/{id}": { "delete": { "operationId": "research_revoke_key", "summary": "Signed-in browser: revoke an owned key", "security": [ { "browserSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/checkout": { "post": { "operationId": "research_checkout", "summary": "Signed-in browser: create a prepaid Stripe Checkout for authorized human payment", "description": "Retain request_id and pack for retries. This does not itself charge a card. No subscription or automatic charges.", "security": [ { "browserSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pack", "request_id" ], "properties": { "pack": { "enum": [ "starter", "builder" ] }, "request_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "409": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/crypto/invoices": { "post": { "operationId": "research_crypto_invoice", "summary": "Create a native SOL, ETH or BTC prepaid invoice; does not send funds", "security": [ { "browserSession": [] }, { "researchApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pack", "chain", "request_id" ], "properties": { "pack": { "enum": [ "starter", "builder" ] }, "chain": { "enum": [ "SOL", "ETH", "BTC" ] }, "request_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "409": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/crypto/invoices/{id}": { "get": { "operationId": "research_crypto_invoice_status", "summary": "Reopen an owned crypto invoice", "security": [ { "browserSession": [] }, { "researchApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "409": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/crypto/invoices/{id}/verify": { "post": { "operationId": "research_crypto_verify", "summary": "Verify native mainnet payment and credit requests exactly once; never signs or sends", "security": [ { "browserSession": [] }, { "researchApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "maxLength": 100 } } } } } }, "responses": { "200": { "description": "JSON response with explicit provenance and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "usage": { "$ref": "#/components/schemas/Usage" }, "next_cursor": { "type": [ "string", "null" ] }, "next_offset": { "type": [ "integer", "null" ] } }, "additionalProperties": true } } } }, "400": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "401": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "402": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "404": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "409": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "429": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } }, "503": { "description": "JSON error; no service request credit is spent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "error": { "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "/paper-gradings": { "get": { "summary": "List your latest 100 paper submissions (session or Bearer key)", "responses": { "200": { "description": "Owned jobs; no API credit debit" }, "401": { "description": "Authentication required" } } }, "post": { "summary": "Submit a paper for six independent assessments and public grades", "description": "Reserves 10,000 prepaid credits once. One $59 Builder pack covers a paper. Monthly free requests do not apply. Retain request_id for safe retries. Complete public full text required. Payment does not affect grades.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "request_id", "title", "doi", "public_consent", "rights_confirmed", "eligible_article" ], "properties": { "request_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "minLength": 10, "maxLength": 500 }, "doi": { "type": "string", "description": "Exact DOI of a publicly available complete manuscript" }, "public_consent": { "type": "boolean", "const": true }, "rights_confirmed": { "type": "boolean", "const": true }, "eligible_article": { "type": "boolean", "const": true } } } } } }, "responses": { "200": { "description": "Idempotent replay; no additional debit" }, "202": { "description": "Queued; credits reserved" }, "400": { "description": "Invalid input or missing consent" }, "401": { "description": "Authentication required" }, "402": { "description": "Insufficient prepaid credits" }, "409": { "description": "Duplicate paper or conflicting request ID" } } } }, "/paper-gradings/{id}/cancel": { "post": { "summary": "Cancel an owned queued/held job and restore reserved credits once", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Credits restored or already restored" }, "401": { "description": "Authentication required" }, "404": { "description": "Owned submission not found" }, "409": { "description": "Active/completed job requires support" } } } } }, "components": { "securitySchemes": { "researchApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "mrk_ + secret" }, "browserSession": { "type": "apiKey", "in": "cookie", "name": "mitograph_session" } }, "schemas": { "Usage": { "type": "object", "properties": { "month": { "type": "string" }, "free_limit": { "type": "integer", "const": 3 }, "free_remaining": { "type": "integer" }, "prepaid_remaining": { "type": "integer" }, "resets_at": { "type": "string", "format": "date-time" }, "charged_from": { "enum": [ "monthly_free", "prepaid" ] } } } } } }