{"openapi":"3.1.0","info":{"title":"BaseCite Stable AI Context API","version":"v1-phase28","summary":"Bounded API for customer-submitted/unverified AI-readable context.","description":"This API exposes controlled, bounded AI context only. Developer discovery: https://basecite.com/docs and Smithery MCP registry listing: https://smithery.ai/servers/alwaysrememberme1024/basecite. It does not verify truth, companies, sources, legal authority, rankings, certification, endorsements, or AI/search adoption."},"servers":[{"url":"https://api.basecite.com"}],"paths":{"/api/v1/ai/capabilities":{"get":{"summary":"Describe BaseCite AI-readable surfaces and boundaries.","responses":{"200":{"description":"Capability metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getAiCapabilitiesResponse"}}}}},"operationId":"getAiCapabilities"}},"/oauth/identity":{"get":{"summary":"Return the organization and scopes bound to the current OAuth bearer token.","security":[{"oauth2":[]}],"responses":{"200":{"description":"Bound OAuth identity and granted scopes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse"}}}},"401":{"description":"Valid OAuth bearer token required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"get__oauth_identity"}},"/portal/config":{"get":{"summary":"Return customer and delegated upload route/config metadata.","responses":{"200":{"description":"Portal config","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getPortalConfigResponse"}}}}},"operationId":"getPortalConfig"}},"/admin/tenant-keys/policy":{"get":{"summary":"Return tenant-scoped credential issuance policy metadata.","responses":{"200":{"description":"Tenant credential policy metadata only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getTenantKeyPolicyResponse"}}}}},"operationId":"getTenantKeyPolicy"}},"/admin/tenant-keys/issue":{"post":{"summary":"Issue an HMAC-signed tenant-scoped beta credential for one org_id and role.","responses":{"201":{"description":"Tenant token returned once to admin caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/issueTenantKeyResponse"}}}},"400":{"description":"Invalid tenant credential request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"issueTenantKey"}},"/api/v1/ai/access-policy":{"get":{"summary":"Return AI/MCP anti-scraping and access policy metadata.","responses":{"200":{"description":"AI access policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getAiAccessPolicyResponse"}}}}},"operationId":"getAiAccessPolicy"}},"/api/v1/organizations/{org_id}/customer-uploads":{"post":{"summary":"Accept customer or delegated-uploader submitted artifacts with required consent capture and non-evaluation labels.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","payload","visibility","consent"],"properties":{"filename":{"type":"string"},"content_type":{"type":"string","example":"text/plain"},"visibility":{"type":"string","enum":["ai_readable_controlled","private_summary_public","internal_only","public_profile"]},"payload":{"type":"string"},"uploader_organization_type":{"type":"string","enum":["customer","solution_company","third_party"]},"uploader_organization_id":{"type":"string"},"asserted_subject_org_id":{"type":"string"},"customer_workspace_access":{"type":"string","enum":["granted","not_granted"]},"consent":{"type":"object","required":["accepted","beta_agreement_version","ai_readable_use_consent_version","text_hash_sha256","consenting_user_id","consenting_user_email","accepted_at"],"properties":{"accepted":{"type":"boolean","const":true},"beta_agreement_version":{"type":"string","example":"controlled-launch-2026-06-19"},"ai_readable_use_consent_version":{"type":"string","example":"ai-readable-use-2026-06-19"},"text_hash_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"consenting_user_id":{"type":"string"},"consenting_user_email":{"type":"string","format":"email"},"accepted_at":{"type":"string","format":"date-time"}}}}}}}},"responses":{"201":{"description":"Upload accepted as non-evaluated provenance record with redacted consent_capture status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/createCustomerUploadResponse"}}}},"400":{"description":"Invalid upload, missing/invalid consent, or forbidden verification claim","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Workspace access boundary blocks customer canonical write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createCustomerUpload","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/organizations/{org_id}/partner-uploads/initiate":{"post":{"summary":"Reserve an authenticated partner upload session. Requires a single-org solution_company_upload service-account credential and a stable Idempotency-Key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","content_type","size_bytes","consent"],"properties":{"filename":{"type":"string"},"content_type":{"type":"string","example":"application/vnd.openxmlformats-officedocument.wordprocessingml.document"},"size_bytes":{"type":"integer","minimum":1,"maximum":8589934592},"notes":{"type":"string"},"material_type":{"type":"string"},"importance":{"type":"string","enum":["normal","important"]},"consent":{"type":"object","required":["accepted","beta_agreement_version","ai_readable_use_consent_version","text_hash_sha256","consenting_user_id","consenting_user_email","accepted_at"],"properties":{"accepted":{"type":"boolean","const":true},"beta_agreement_version":{"type":"string","example":"controlled-launch-2026-06-19"},"ai_readable_use_consent_version":{"type":"string","example":"ai-readable-use-2026-06-19"},"text_hash_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"consenting_user_id":{"type":"string"},"consenting_user_email":{"type":"string","format":"email"},"accepted_at":{"type":"string","format":"date-time"}}}}}}}},"responses":{"200":{"description":"Multipart upload reserved; response includes upload_id and part_size_bytes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/initiatePartnerUploadResponse"}}}},"401":{"description":"A properly bound partner service-account credential is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key replay or conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"initiatePartnerUpload","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/organizations/{org_id}/partner-uploads/part":{"put":{"summary":"Upload one sequential binary part to a reserved partner upload. Query parameters: upload_id, part_number.","responses":{"200":{"description":"Part accepted into private staging","content":{"application/json":{"schema":{"$ref":"#/components/schemas/uploadPartnerPartResponse"}}}},"409":{"description":"Sequential part or upload identity conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"uploadPartnerPart","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/organizations/{org_id}/partner-uploads/complete":{"post":{"summary":"Complete a reserved partner upload. BaseCite verifies the server-streamed SHA-256, mirrors it to AWS quarantine, then starts the existing malware/OCR processing path.","responses":{"200":{"description":"Upload processing accepted or idempotent replay returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/completePartnerUploadResponse"}}}},"202":{"description":"Upload accepted as an asynchronous processing job; poll the canonical upload status resource until a terminal state.","links":{"status":{"operationId":"getPartnerUploadStatus","parameters":{"org_id":"$request.path.org_id","upload_id":"$response.body#/data/upload_id"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/completePartnerUploadResponse"}}}},"409":{"description":"Multipart ledger or digest verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"completePartnerUpload","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/organizations/{org_id}/partner-uploads/{upload_id}":{"get":{"summary":"Return metadata-only progress for the authenticated partner service account upload.","responses":{"200":{"description":"In-progress or completed metadata-only upload status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getPartnerUploadStatusResponse"}}}},"404":{"description":"Upload not found for this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getPartnerUploadStatus"}},"/api/v1/organizations/{org_id}/partner-uploads/{upload_id}/withdraw":{"post":{"summary":"Permanently delete one partner upload and all derived AI context using an exactly bound solution_company_upload or managed Genvernium super-admin credential.","responses":{"200":{"description":"Customer raw payload, storage copies, derived AI context, and quota bytes deleted; audit metadata and deletion receipt retained.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/withdrawPartnerUploadResponse"}}}},"403":{"description":"Exactly bound upload credential or managed Genvernium super-admin credential required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Upload not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Deletion could not be confirmed in every configured storage backend","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"withdrawPartnerUpload","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/organizations/{org_id}/customer-uploads/{upload_id}/corrections":{"post":{"summary":"Accept correction as a new upload with required consent capture; original upload is not overwritten.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","payload","visibility","consent"],"properties":{"filename":{"type":"string"},"content_type":{"type":"string","example":"text/plain"},"visibility":{"type":"string","enum":["ai_readable_controlled","private_summary_public","internal_only","public_profile"]},"payload":{"type":"string"},"uploader_organization_type":{"type":"string","enum":["customer","solution_company","third_party"]},"uploader_organization_id":{"type":"string"},"asserted_subject_org_id":{"type":"string"},"customer_workspace_access":{"type":"string","enum":["granted","not_granted"]},"consent":{"type":"object","required":["accepted","beta_agreement_version","ai_readable_use_consent_version","text_hash_sha256","consenting_user_id","consenting_user_email","accepted_at"],"properties":{"accepted":{"type":"boolean","const":true},"beta_agreement_version":{"type":"string","example":"controlled-launch-2026-06-19"},"ai_readable_use_consent_version":{"type":"string","example":"ai-readable-use-2026-06-19"},"text_hash_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"consenting_user_id":{"type":"string"},"consenting_user_email":{"type":"string","format":"email"},"accepted_at":{"type":"string","format":"date-time"}}}}}}}},"responses":{"201":{"description":"Correction accepted as new non-evaluated upload with redacted consent_capture status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/createUploadCorrectionResponse"}}}},"400":{"description":"Invalid correction, missing/invalid consent, or forbidden verification claim","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Original upload not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createUploadCorrection","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/organizations/{org_id}/customer-uploads/{upload_id}/origin-cairn-review":{"post":{"summary":"Attach an optional OriginCairn review reference without changing original provenance.","responses":{"200":{"description":"Reference attached; evaluation remains not_evaluated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/createOriginCairnReviewResponse"}}}},"400":{"description":"Invalid or overclaiming reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createOriginCairnReview","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/organizations/{org_id}/ai-context/{upload_id}":{"get":{"summary":"Return bounded AI context for one upload when visibility allows.","security":[{"aiReaderApiKey":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"upload_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Bounded customer-submitted/unverified AI context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getAiContextResponse"}}}},"401":{"description":"AI reader API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Visibility tier does not allow AI context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Upload not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getAiContext"}},"/api/v1/organizations/{org_id}/request-records":{"get":{"summary":"Return serving evidence records for bounded API/MCP reads.","security":[{"aiReaderApiKey":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"request_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"upload_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Serving evidence record metadata with schema disclaimer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/listRequestRecordsResponse"}}}},"401":{"description":"API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listRequestRecords"}}},"webhooks":{"uploadStatusChanged":{"post":{"summary":"Receive a signed status transition for one organization-scoped upload.","description":"The callback URL and signing secret are configured per tenant through a secure channel. Consumers must deduplicate event_id, enforce immutable sequence ordering, and recover gaps through the canonical status endpoint.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event_id","upload_id","sequence","status","occurred_at"],"properties":{"event_id":{"type":"string"},"upload_id":{"type":"string"},"pipeline_id":{"type":"string"},"sequence":{"type":"integer","minimum":1},"status":{"type":"string"},"stage":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"},"request_id":{"type":"string"},"trace_id":{"type":"string"}}}}}},"responses":{"202":{"description":"Event accepted idempotently"},"400":{"description":"Invalid signature or event shape"},"409":{"description":"Duplicate, stale, or out-of-order sequence"}}}}},"components":{"schemas":{"Error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"trace_id":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"ApiResponse":{"type":"object","additionalProperties":true,"properties":{"request_id":{"type":"string"},"trace_id":{"type":"string"},"data":{"type":"object","additionalProperties":true}}},"getAiCapabilitiesResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","required":["status","api_contract","endpoints","data_boundary"],"properties":{"status":{"type":"string"},"api_contract":{"type":"string"},"endpoints":{"type":"object","additionalProperties":{"type":"string"}},"data_boundary":{"type":"object","additionalProperties":{"type":["boolean","string"]}}},"additionalProperties":true}}}]},"getPortalConfigResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"entry":{"type":"string","format":"uri"},"account_required":{"type":"boolean"},"email_verification_required":{"type":"boolean"},"customer_authorized_uploaders_only":{"type":"boolean"}},"additionalProperties":true}}}]},"getTenantKeyPolicyResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"role":{"type":"string"},"org_id":{"type":"string"},"scope":{"type":"string"},"metadata_read":{"type":"boolean"},"ai_readiness":{"type":"boolean"}},"additionalProperties":true}}}]},"issueTenantKeyResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"credential_id":{"type":"string"},"org_id":{"type":"string"},"role":{"type":"string"},"scope":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":true}}}]},"getAiAccessPolicyResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"access_mode":{"type":"string"},"public_discovery":{"type":"boolean"},"raw_payload_download":{"type":"boolean"},"bulk_export":{"type":"boolean"}},"additionalProperties":true}}}]},"createCustomerUploadResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"upload_id":{"type":"string"},"org_id":{"type":"string"},"status":{"type":"string"},"filename":{"type":"string"},"consent_capture":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}]},"initiatePartnerUploadResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","required":["upload_id","part_size_bytes"],"properties":{"upload_id":{"type":"string"},"part_size_bytes":{"type":"integer","minimum":1},"status":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":true}}}]},"uploadPartnerPartResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"upload_id":{"type":"string"},"part_number":{"type":"integer","minimum":1},"sequence":{"type":"integer","minimum":1},"status":{"type":"string"}},"additionalProperties":true}}}]},"completePartnerUploadResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"upload_id":{"type":"string"},"pipeline_id":{"type":"string"},"status":{"type":"string"},"sequence":{"type":"integer","minimum":1},"sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"additionalProperties":true}}}]},"getPartnerUploadStatusResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"upload_id":{"type":"string"},"pipeline_id":{"type":"string"},"status":{"type":"string"},"sequence":{"type":"integer","minimum":1},"gates":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true}}}]},"withdrawPartnerUploadResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"upload_id":{"type":"string"},"status":{"type":"string","enum":["WITHDRAWN"]},"deleted":{"type":"boolean"},"withdrawal_receipt_id":{"type":"string"},"quota_bytes":{"type":"integer","minimum":0}},"additionalProperties":true}}}]},"createUploadCorrectionResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"upload_id":{"type":"string"},"original_upload_id":{"type":"string"},"status":{"type":"string"},"consent_capture":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}]},"createOriginCairnReviewResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"upload_id":{"type":"string"},"review_id":{"type":"string"},"evaluation_status":{"type":"string","enum":["not_evaluated"]}},"additionalProperties":true}}}]},"getAiContextResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","required":["upload_id"],"properties":{"upload_id":{"type":"string"},"org_id":{"type":"string"},"visibility":{"type":"string"},"context":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}]},"listRequestRecordsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","additionalProperties":true}},"next_cursor":{"type":"string"}},"additionalProperties":true}}}]}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable replay key for a single mutation request.","schema":{"type":"string","minLength":8,"maxLength":128}}},"securitySchemes":{"aiReaderApiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.basecite.com/oauth/token","scopes":{"customer_upload":"Create and complete organization-scoped customer uploads.","metadata_read":"Read metadata and canonical upload status for the bound organization.","ai_readiness":"Read bounded AI-readiness and processing metadata for the bound organization.","ai_context":"Read bounded AI context for the bound organization.","mcp":"Use authenticated bounded MCP tools for the bound organization.","correction":"Create organization-scoped upload corrections.","origin_cairn_reference":"Attach organization-scoped OriginCairn references."}}}}}},"x-basecite-boundary":"customer_submitted_unverified_private_beta","x-basecite-public-downloadable":false,"x-basecite-bulk-export":false,"x-basecite-api-lifecycle":{"policy_url":"https://basecite.com/docs/developers#versioning-and-deprecation","versioning":"URL versioning under /api/v1/","deprecation_notice":"Retiring operations advertise Deprecation and Sunset response headers at least 90 days before removal.","compatibility":"Existing v1 operations remain backward-compatible during the published support window."},"x-basecite-truth-verification-claim":false,"x-basecite-phase32-solution-company-upload":true,"x-basecite-phase33-self-documenting-status-sync":true,"x-basecite-phase34-portal-ux":true,"x-basecite-phase35-private-object-storage-boundary":true,"x-basecite-phase36-ai-mcp-anti-scraping-access-policy":true,"x-basecite-phase37-tenant-scoped-credentials":true,"x-basecite-deprecation-policy":"Breaking changes require a new /api/vN path. Deprecated fields remain documented for one version and emit Deprecation and Sunset headers before removal.","x-basecite-async-job-pattern":"Long-running processing is represented by upload status polling and immutable sequence transitions; clients must not infer completion from elapsed time.","x-basecite-rate-limit":{"headers":["RateLimit-Limit","RateLimit-Remaining","RateLimit-Reset","Retry-After"],"response":429},"x-basecite-pagination":"List-like responses use explicit limit and cursor metadata when available; clients must not infer completeness from a truncated page."}