APIAPI reference
Report a source-backed observation issue
POST /v1/reports
POST /v1/reports
Non-billable; needs a verified workspace member with kb:query. The gateway captures an immutable original snapshot, stable source reference, dataset revision and record digest. Use the same idempotency key for the same finding. Reusing a key for different input is a 409. Include only the observation discrepancy and source evidence, never private user queries or secrets. A pending report does not modify any scientific data. Limited to 20 submissions per user/hour and 200 per workspace/hour; this is separate from billing and knowledge query limits.
Authorization
This operation requires a bearer credential. The description defines additional role, scope or first-party-session restrictions; an API key does not grant those permissions by itself.
Request body
| Property | Type | Required | Details |
|---|---|---|---|
observation_id | string | yes | |
category | "field_conflict" ∣ "stage_misattribution" ∣ "missing_source" ∣ "structure_mismatch" ∣ "other" | yes | |
summary | string | yes | Only the observed record issue; no user query or private context. |
evidence_quote | string ∣ null | no | |
proposed_patch | CorrectionPatch ∣ null | no | |
idempotency_key | string | yes |
Full schema: ReportSubmission
{
"properties": {
"observation_id": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"title": "Observation Id"
},
"category": {
"type": "string",
"enum": [
"field_conflict",
"stage_misattribution",
"missing_source",
"structure_mismatch",
"other"
],
"title": "Category"
},
"summary": {
"type": "string",
"maxLength": 2000,
"minLength": 10,
"title": "Summary",
"description": "Only the observed record issue; no user query or private context."
},
"evidence_quote": {
"anyOf": [
{
"type": "string",
"maxLength": 4000,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Evidence Quote"
},
"proposed_patch": {
"anyOf": [
{
"$ref": "#/components/schemas/CorrectionPatch"
},
{
"type": "null"
}
]
},
"idempotency_key": {
"type": "string",
"maxLength": 128,
"minLength": 8,
"pattern": "^[A-Za-z0-9_.:-]+$",
"title": "Idempotency Key"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"observation_id",
"category",
"summary",
"idempotency_key"
],
"title": "ReportSubmission"
}Responses
| HTTP | Details | Type |
|---|---|---|
| 201 | Successful Response | application/json: ObservationReport |
| 401 | Unauthorized | application/problem+json: ProblemDetails |
| 403 | Forbidden | application/problem+json: ProblemDetails |
| 404 | Not Found | application/problem+json: ProblemDetails |
| 409 | Conflict | application/problem+json: ProblemDetails |
| 413 | Request Entity Too Large | application/problem+json: ProblemDetails |
| 422 | Unprocessable Entity | application/problem+json: ProblemDetails |
| 429 | Too Many Requests | application/problem+json: ProblemDetails |
| 502 | Bad Gateway | application/problem+json: ProblemDetails |
| 503 | Service Unavailable | application/problem+json: ProblemDetails |
Response: ObservationReport
| Property | Type | Required | Details |
|---|---|---|---|
id | string | yes | |
observation_id | string | yes | |
category | "field_conflict" ∣ "stage_misattribution" ∣ "missing_source" ∣ "structure_mismatch" ∣ "other" | yes | |
summary | string | yes | |
evidence_quote | string ∣ null | no | |
proposed_patch | CorrectionPatch ∣ null | no | |
state | "pending" ∣ "accepted" ∣ "rejected" ∣ "needs_information" ∣ "needs_revalidation" | yes | |
created_at | string | yes | |
updated_at | string | yes | |
reference | ReportReference | yes | |
review | ReviewedDecision ∣ null | no | |
correction | CorrectionVersion ∣ null | no |
Full schema
{
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"observation_id": {
"type": "string",
"title": "Observation Id"
},
"category": {
"type": "string",
"enum": [
"field_conflict",
"stage_misattribution",
"missing_source",
"structure_mismatch",
"other"
],
"title": "Category"
},
"summary": {
"type": "string",
"title": "Summary"
},
"evidence_quote": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Evidence Quote"
},
"proposed_patch": {
"anyOf": [
{
"$ref": "#/components/schemas/CorrectionPatch"
},
{
"type": "null"
}
]
},
"state": {
"type": "string",
"enum": [
"pending",
"accepted",
"rejected",
"needs_information",
"needs_revalidation"
],
"title": "State"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"updated_at": {
"type": "string",
"title": "Updated At"
},
"reference": {
"$ref": "#/components/schemas/ReportReference"
},
"review": {
"anyOf": [
{
"$ref": "#/components/schemas/ReviewedDecision"
},
{
"type": "null"
}
]
},
"correction": {
"anyOf": [
{
"$ref": "#/components/schemas/CorrectionVersion"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true,
"type": "object",
"required": [
"id",
"observation_id",
"category",
"summary",
"state",
"created_at",
"updated_at",
"reference"
],
"title": "ObservationReport"
}This page is generated from OpenAPI; examples are schemas, not a fabricated successful response.