{"openapi":"3.1.0","info":{"title":"CiteArk Agent API","version":"1.1.0","description":"Token-efficient access to research plans, physical executions, immutable Assessments, and Evidence. Public reads need no key; private reads and run requests accept x-api-key or Authorization: Bearer.","contact":{"url":"https://citeark.com/contact"}},"servers":[{"url":"https://citeark.com"}],"externalDocs":{"url":"https://citeark.com/docs/agent-api"},"tags":[{"name":"Research"},{"name":"Claims"},{"name":"Runs"},{"name":"Evidence"}],"paths":{"/api/v1/search":{"get":{"operationId":"searchResearch","tags":["Research"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"subject","in":"query","schema":{"type":"string"}},{"name":"repository_cursor","in":"query","schema":{"type":"string"}},{"name":"claim_cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"}}}}}}},"/api/v1/repositories":{"get":{"operationId":"listRepositories","tags":["Research"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"subject","in":"query","schema":{"type":"string"}},{"name":"verification","in":"query","schema":{"enum":["unverified","queued","running","verified","failed","inconclusive","review_required","cancelled","timed_out"]}},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"fields","in":"query","description":"Comma-separated top-level response fields.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}}}}},"/api/v1/repositories/{repositoryId}":{"get":{"operationId":"getRepository","tags":["Research"],"parameters":[{"name":"repositoryId","in":"path","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","description":"readme,claims,experiments,runs,evidence,assessments","schema":{"type":"string"}},{"name":"fields","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepositorySummary"}}}}}}},"/api/v1/repositories/resolve":{"get":{"operationId":"resolveRepositoryByPath","tags":["Research"],"description":"Resolve a human repository path to the canonical compact Agent API record. Repository HTML URLs also negotiate this representation with Accept: application/json.","parameters":[{"name":"owner","in":"query","required":true,"schema":{"type":"string"}},{"name":"slug","in":"query","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","description":"readme,claims,experiments,runs,evidence,assessments","schema":{"type":"string"}},{"name":"fields","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepositorySummary"}}}}}}},"/api/v1/claims":{"get":{"operationId":"listClaims","tags":["Claims"],"parameters":[{"name":"repository_id","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"verification","in":"query","schema":{"enum":["unverified","queued","running","verified","failed","inconclusive","review_required","cancelled","timed_out"]}},{"name":"include","in":"query","description":"assessments","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"fields","in":"query","description":"Comma-separated top-level response fields.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}}}}},"/api/v1/claims/{claimId}":{"get":{"operationId":"getClaim","tags":["Claims"],"parameters":[{"name":"claimId","in":"path","required":true,"schema":{"type":"string"}},{"name":"repository_id","in":"query","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","description":"assessments","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Claim"}}}}}}},"/api/v1/runs":{"get":{"operationId":"listRuns","tags":["Runs"],"parameters":[{"name":"repository_id","in":"query","schema":{"type":"string"}},{"name":"claim_id","in":"query","schema":{"type":"string"}},{"name":"state","in":"query","deprecated":true,"description":"Legacy combined state filter.","schema":{"enum":["unverified","queued","running","verified","failed","inconclusive","review_required","cancelled","timed_out"]}},{"name":"execution_state","in":"query","schema":{"enum":["queued","running","succeeded","failed","partial","cancelled","timedOut","unknown"]}},{"name":"assessment_conclusion","in":"query","schema":{"enum":["supports","challenges","contradicts","inconclusive"]}},{"name":"include","in":"query","description":"environment,attestation,logs,evidence,assessments","schema":{"type":"string"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"fields","in":"query","description":"Comma-separated top-level response fields.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}}}}},"post":{"operationId":"requestReproduction","tags":["Runs"],"security":[{"apiKey":[]},{"bearerApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["repositoryId","claimId"],"properties":{"repositoryId":{"type":"string"},"claimId":{"type":"string"},"experimentVersionId":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"}}}}}},"responses":{"202":{"description":"Run queued"}}}},"/api/v1/runs/{runId}":{"get":{"operationId":"getRun","tags":["Runs"],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}},{"name":"repository_id","in":"query","schema":{"type":"string"}},{"name":"include","in":"query","description":"environment,attestation,logs,evidence,assessments","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}}}}},"/api/v1/evidence/{evidenceId}":{"get":{"operationId":"getEvidence","tags":["Evidence"],"parameters":[{"name":"evidenceId","in":"path","required":true,"schema":{"type":"string"}},{"name":"repository_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response. Supports ETag/If-None-Match and public cache revalidation.","headers":{"ETag":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Evidence"}}}}}}}},"components":{"schemas":{"Links":{"type":"object","additionalProperties":{"type":["string","null"]}},"Diagnostic":{"type":"object","required":["code","category","retryable","summary","recoveryAction"],"properties":{"code":{"type":"string"},"category":{"enum":["source","measurement","environment","resource","timeout","execution","unknown"]},"retryable":{"type":["boolean","null"]},"summary":{"type":"string"},"recoveryAction":{"type":["string","null"]}}},"AssessmentCounts":{"type":"object","required":["supports","challenges","contradicts","inconclusive"],"properties":{"supports":{"type":"integer","minimum":0},"challenges":{"type":"integer","minimum":0},"contradicts":{"type":"integer","minimum":0},"inconclusive":{"type":"integer","minimum":0}}},"Assessment":{"type":"object","required":["id","recordDigest","artifactDigest","claimVersionId","experimentVersionId","executionRunId","supersedesAssessmentDigests","conclusion","verificationStatus","confidence","protocolComparability","method","evidenceIds","scope","limitations","assessor","createdAt"],"properties":{"id":{"type":"string"},"recordDigest":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"artifactDigest":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"claimVersionId":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"experimentVersionId":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"executionRunId":{"type":"string"},"supersedesAssessmentDigests":{"type":"array","items":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"}},"current":{"type":"boolean"},"conclusion":{"enum":["supports","challenges","contradicts","inconclusive"]},"verificationStatus":{"enum":["reproduced","approximately_reproduced","not_reproduced","inconclusive",null]},"confidence":{"enum":["high","medium","low",null]},"protocolComparability":{"enum":["exact","minor_difference","material_difference","unknown",null]},"method":{"enum":["MetricComparison","DirectionalComparison","QualitativeReview","IntegrityOnly"]},"evidenceIds":{"type":"array","items":{"type":"string"}},"scope":{"type":"object"},"limitations":{"type":"array","items":{"type":"string"}},"assessor":{"type":"object"},"createdAt":{"type":"string","format":"date-time"}}},"Measurement":{"type":"object","required":["measurementId","metric","unit","reportedValue","observedValue","verification","evidenceIds"],"properties":{"measurementId":{"type":"string","description":"Stable identity; never use metric name as identity."},"metric":{"type":"string"},"unit":{"type":"string"},"dimensions":{"type":"object","additionalProperties":true},"comparator":{"enum":[">=","<=","=","~="]},"reportedValue":{"type":["number","null"]},"observedValue":{"type":["number","null"]},"tolerance":{"type":["number","null"]},"absoluteDifference":{"type":["number","null"]},"verification":{"enum":["unverified","queued","running","verified","failed","inconclusive","review_required","cancelled","timed_out"]},"reason":{"type":["string","null"]},"diagnostic":{"anyOf":[{"$ref":"#/components/schemas/Diagnostic"},{"type":"null"}]},"evidenceIds":{"type":"array","items":{"type":"string"}}}},"RepositorySummary":{"type":"object","required":["id","title","visibility","authors","subjects","verification","evidence","execution","links"],"properties":{"id":{"type":"string"},"owner":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"significance":{"type":["string","null"]},"visibility":{"enum":["public","private"]},"authors":{"type":"array","items":{"type":"string"}},"subjects":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"verification":{"type":"object","deprecated":true,"description":"Compatibility progress projection. Use evidence and execution for scientific and physical state.","properties":{"rings":{"type":"object","properties":{"run":{"type":"boolean"},"match":{"type":"boolean"},"repeat":{"type":"boolean"},"institutionVerified":{"type":"boolean"}}},"claimCount":{"type":"integer"},"verifiedClaimCount":{"type":"integer"},"runCount":{"type":"integer"}}},"evidence":{"type":"object","required":["stateCounts","claimCount","assessedClaimCount","supportedClaimCount"],"properties":{"stateCounts":{"type":"object","properties":{"supported":{"type":"integer","minimum":0},"challenged":{"type":"integer","minimum":0},"contradicted":{"type":"integer","minimum":0},"mixed":{"type":"integer","minimum":0},"inconclusive":{"type":"integer","minimum":0},"notAssessed":{"type":"integer","minimum":0}}},"claimCount":{"type":"integer","minimum":0},"assessedClaimCount":{"type":"integer","minimum":0},"supportedClaimCount":{"type":"integer","minimum":0}}},"execution":{"type":"object","required":["runCount","stateCounts"],"properties":{"runCount":{"type":"integer","minimum":0},"stateCounts":{"type":"object","properties":{"queued":{"type":"integer","minimum":0},"running":{"type":"integer","minimum":0},"succeeded":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"partial":{"type":"integer","minimum":0},"cancelled":{"type":"integer","minimum":0},"timedOut":{"type":"integer","minimum":0},"unknown":{"type":"integer","minimum":0}}}}},"updatedAt":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/Links"}}},"Claim":{"type":"object","required":["id","repository","verification","plan","evidence","measurements","links"],"properties":{"id":{"type":"string"},"repository":{"type":"object"},"type":{"type":"string"},"statement":{"type":"string"},"sourceLocator":{"type":"string"},"verification":{"enum":["unverified","queued","running","verified","failed","inconclusive","review_required","cancelled","timed_out"],"deprecated":true,"description":"Legacy combined state. Use plan and evidence."},"reproduction":{"type":["object","null"],"deprecated":true,"description":"Compatibility alias for plan."},"plan":{"type":["object","null"],"description":"Research execution plan; not an execution result."},"evidence":{"type":"object","required":["state","assessmentCount","conclusionCounts","latestAssessmentAt"],"properties":{"state":{"enum":["supported","challenged","contradicted","mixed","inconclusive","notAssessed"]},"assessmentCount":{"type":"integer","minimum":0},"conclusionCounts":{"$ref":"#/components/schemas/AssessmentCounts"},"latestAssessmentAt":{"type":["string","null"],"format":"date-time"}}},"assessments":{"type":"array","items":{"$ref":"#/components/schemas/Assessment"}},"measurements":{"type":"array","items":{"$ref":"#/components/schemas/Measurement"}},"experimentIds":{"type":"array","items":{"type":"string"}},"evidenceIds":{"type":"array","items":{"type":"string"}},"links":{"$ref":"#/components/schemas/Links"}}},"Run":{"type":"object","required":["id","repository","state","execution","assessment","claimIds","measurements","links"],"properties":{"id":{"type":"string"},"repository":{"type":"object"},"state":{"enum":["unverified","queued","running","verified","failed","inconclusive","review_required","cancelled","timed_out"],"deprecated":true,"description":"Legacy combined state. Use execution.state and assessment.conclusion."},"execution":{"type":"object","required":["state","failure"],"properties":{"state":{"enum":["queued","running","succeeded","failed","partial","cancelled","timedOut","unknown"]},"failure":{"anyOf":[{"$ref":"#/components/schemas/Diagnostic"},{"type":"null"}]}}},"assessment":{"type":"object","required":["conclusion","assessmentCount","conclusionCounts","latestAssessmentAt"],"properties":{"conclusion":{"enum":["supports","challenges","contradicts","inconclusive",null]},"assessmentCount":{"type":"integer","minimum":0},"conclusionCounts":{"$ref":"#/components/schemas/AssessmentCounts"},"latestAssessmentAt":{"type":["string","null"],"format":"date-time"}}},"assessments":{"type":"array","items":{"$ref":"#/components/schemas/Assessment"}},"claimIds":{"type":"array","items":{"type":"string"}},"experimentVersionId":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"queuedAt":{"type":"string","format":"date-time"},"startedAt":{"type":["string","null"],"format":"date-time"},"finishedAt":{"type":["string","null"],"format":"date-time"},"measurements":{"type":"array","items":{"$ref":"#/components/schemas/Measurement"}},"agent":{"type":"object"},"artifact":{"type":["object","null"]},"environment":{"type":"object"},"attestation":{"type":"object"},"logs":{"type":"array","items":{"type":"object"}},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}},"links":{"$ref":"#/components/schemas/Links"}}},"Evidence":{"type":"object","required":["id","repositoryId","kind","digest","generatedByRunId","downloadUrl","links"],"properties":{"id":{"type":"string"},"repositoryId":{"type":"string"},"kind":{"enum":["metric","artifact","log","checkpoint","figure"]},"digest":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"summary":{"type":"string"},"generatedByRunId":{"type":"string"},"sourcePath":{"type":["string","null"]},"mediaType":{"type":["string","null"]},"byteSize":{"type":["integer","null"],"minimum":0},"downloadUrl":{"type":"string","format":"uri"},"links":{"$ref":"#/components/schemas/Links"}}},"Page":{"type":"object","required":["data","pagination","links"],"properties":{"data":{"type":"array","items":{}},"pagination":{"type":"object","required":["nextCursor","hasMore"],"properties":{"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"}}},"links":{"$ref":"#/components/schemas/Links"}}},"SearchResult":{"type":"object","required":["data","pagination","meta"],"properties":{"data":{"type":"object","required":["repositories","claims"],"properties":{"repositories":{"type":"array","items":{"$ref":"#/components/schemas/RepositorySummary"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}}},"pagination":{"type":"object","properties":{"repositories":{"type":"object"},"claims":{"type":"object"}}},"meta":{"type":"object"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object"}}}}}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"CiteArk API Key"}}},"x-mcp":{"endpoint":"https://citeark.com/mcp","transport":"streamable-http"}}