V12 Documents API
The Documents API from V12 — 3 operation(s) for documents.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/v12:v12-documents-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: V12 Documents API
version: 2.0.0
description: Findings, runs and context documents of one V12 organization. Every path but /me sits under /orgs/{org}, where {org} is the organization's slug (GET /me returns it); a token reaches only its own organization, and any other slug answers 404.
servers:
- url: https://v12.sh/api/v2
tags:
- name: Documents
paths:
/orgs/{org}/documents/uploads:
post:
operationId: requestDocumentUpload
summary: Request a document upload slot
description: 'Get a URL to PUT a file to (up to 50 MiB, valid 10 minutes), then call create_document with the slot id. Types: PDF, Markdown, text, JSON, DOCX, CSV.'
tags:
- Documents
security:
- bearer: []
- oauth2:
- runs:write
x-mcp-tool: request_document_upload
parameters:
- name: org
in: path
required: true
description: Organization slug; must be the token's organization.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
filename:
type: string
minLength: 1
maxLength: 255
contentType:
type: string
minLength: 1
maxLength: 255
description: MIME type of the file.
required:
- filename
- contentType
responses:
'201':
description: Request a document upload slot
content:
application/json:
schema:
type: object
properties:
upload:
type: object
properties:
id:
type: string
url:
type: string
method:
type: string
const: PUT
headers:
type: object
properties:
Content-Type:
type: string
required:
- Content-Type
additionalProperties: false
expiresAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
maxBytes:
type: number
const: 52428800
required:
- id
- url
- method
- headers
- expiresAt
- maxBytes
additionalProperties: false
required:
- upload
additionalProperties: false
'400':
description: The request is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Missing or invalid bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'403':
description: The token lacks a scope, or its user lacks a permission
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'404':
description: Not found in the token organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'409':
description: The request conflicts with the current state
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'413':
description: The body exceeds 1 MiB
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'415':
description: The body is not application/json
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'429':
description: Rate limited; see Retry-After
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
/orgs/{org}/documents:
post:
operationId: createDocument
summary: Create a context document
description: 'Add a context document runs can read: an uploaded file ({ upload }) or a text note ({ note }). Identical content returns the existing document with its original title (created: false); if that document was archived, this restores it (restored: true). An upload slot works once.'
tags:
- Documents
security:
- bearer: []
- oauth2:
- runs:write
x-mcp-tool: create_document
parameters:
- name: org
in: path
required: true
description: Organization slug; must be the token's organization.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
upload:
type: object
properties:
id:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
title:
type: string
minLength: 1
maxLength: 200
required:
- id
- title
additionalProperties: false
note:
type: object
properties:
title:
type: string
minLength: 1
maxLength: 200
text:
type: string
minLength: 1
required:
- title
- text
additionalProperties: false
required: []
responses:
'201':
description: Create a context document
content:
application/json:
schema:
type: object
properties:
document:
type: object
properties:
id:
type: string
title:
type: string
kind:
type: string
enum:
- upload
- note
contentType:
type: string
extension:
type: string
bytes:
type: integer
minimum: 0
maximum: 9007199254740991
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
archived:
type: boolean
usedInRuns:
type: integer
minimum: 0
maximum: 9007199254740991
recommended:
type: boolean
createdBy:
anyOf:
- type: object
properties:
username:
anyOf:
- type: string
- type: 'null'
email:
anyOf:
- type: string
- type: 'null'
required:
- username
- email
additionalProperties: false
- type: 'null'
required:
- id
- title
- kind
- contentType
- extension
- bytes
- createdAt
- archived
- usedInRuns
- recommended
- createdBy
additionalProperties: false
created:
type: boolean
description: 'False when identical content already existed: that document comes back with its original title.'
restored:
type: boolean
description: True when that existing document was archived and is now restored.
required:
- document
- created
- restored
additionalProperties: false
'400':
description: The request is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Missing or invalid bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'403':
description: The token lacks a scope, or its user lacks a permission
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'404':
description: Not found in the token organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'409':
description: The request conflicts with the current state
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'413':
description: The body exceeds 1 MiB
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'415':
description: The body is not application/json
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'429':
description: Rate limited; see Retry-After
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
get:
operationId: listDocuments
summary: List context documents
description: 'Context documents of the organization, newest first. With repository, documents used by earlier runs on that repository come first and have recommended: true; it ranks, it does not filter.'
tags:
- Documents
security:
- bearer: []
- oauth2:
- runs:read
x-mcp-tool: list_documents
parameters:
- name: org
in: path
required: true
description: Organization slug; must be the token's organization.
schema:
type: string
- name: repository
in: query
required: false
schema:
type: string
pattern: ^[^/\s]+\/[^/\s]+$
description: Repository slug or full name, "owner/name".
- name: archived
in: query
required: false
schema:
default: false
type: boolean
- name: limit
in: query
required: false
schema:
default: 50
type: integer
minimum: 1
maximum: 100
- name: cursor
in: query
required: false
schema:
type: string
minLength: 1
maxLength: 2048
description: '`nextCursor` from the previous page.'
responses:
'200':
description: List context documents
content:
application/json:
schema:
type: object
properties:
nextCursor:
anyOf:
- type: string
- type: 'null'
items:
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
kind:
type: string
enum:
- upload
- note
contentType:
type: string
extension:
type: string
bytes:
type: integer
minimum: 0
maximum: 9007199254740991
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
archived:
type: boolean
usedInRuns:
type: integer
minimum: 0
maximum: 9007199254740991
recommended:
type: boolean
createdBy:
anyOf:
- type: object
properties:
username:
anyOf:
- type: string
- type: 'null'
email:
anyOf:
- type: string
- type: 'null'
required:
- username
- email
additionalProperties: false
- type: 'null'
required:
- id
- title
- kind
- contentType
- extension
- bytes
- createdAt
- archived
- usedInRuns
- recommended
- createdBy
additionalProperties: false
required:
- nextCursor
- items
additionalProperties: false
'400':
description: The request is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Missing or invalid bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'403':
description: The token lacks a scope, or its user lacks a permission
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'404':
description: Not found in the token organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'409':
description: The request conflicts with the current state
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'429':
description: Rate limited; see Retry-After
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
/orgs/{org}/documents/{document}:
get:
operationId: getDocument
summary: Get a context document
description: One context document by id.
tags:
- Documents
security:
- bearer: []
- oauth2:
- runs:read
parameters:
- name: org
in: path
required: true
description: Organization slug; must be the token's organization.
schema:
type: string
- name: document
in: path
required: true
schema:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: Context document id.
responses:
'200':
description: Get a context document
content:
application/json:
schema:
type: object
properties:
document:
type: object
properties:
id:
type: string
title:
type: string
kind:
type: string
enum:
- upload
- note
contentType:
type: string
extension:
type: string
bytes:
type: integer
minimum: 0
maximum: 9007199254740991
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
archived:
type: boolean
usedInRuns:
type: integer
minimum: 0
maximum: 9007199254740991
recommended:
type: boolean
createdBy:
anyOf:
- type: object
properties:
username:
anyOf:
- type: string
- type: 'null'
email:
anyOf:
- type: string
- type: 'null'
required:
- username
- email
additionalProperties: false
- type: 'null'
required:
- id
- title
- kind
- contentType
- extension
- bytes
- createdAt
- archived
- usedInRuns
- recommended
- createdBy
additionalProperties: false
required:
- document
additionalProperties: false
'400':
description: The request is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Missing or invalid bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'403':
description: The token lacks a scope, or its user lacks a permission
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'404':
description: Not found in the token organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'409':
description: The request conflicts with the current state
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'429':
description: Rate limited; see Retry-After
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
delete:
operationId: archiveDocument
summary: Archive a context document
description: Archive a document so new runs refuse it (estimate_run and start_run answer conflict). Creating identical content again restores it. Only its creator or an owner may archive it.
tags:
- Documents
security:
- bearer: []
- oauth2:
- runs:write
x-mcp-tool: archive_document
parameters:
- name: org
in: path
required: true
description: Organization slug; must be the token's organization.
schema:
type: string
- name: document
in: path
required: true
schema:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: Context document id.
responses:
'200':
description: Archive a context document
content:
application/json:
schema:
type: object
properties:
document:
type: object
properties:
id:
type: string
title:
type: string
kind:
type: string
enum:
- upload
- note
contentType:
type: string
extension:
type: string
bytes:
type: integer
minimum: 0
maximum: 9007199254740991
createdAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
archived:
type: boolean
usedInRuns:
type: integer
minimum: 0
maximum: 9007199254740991
recommended:
type: boolean
createdBy:
anyOf:
- type: object
properties:
username:
anyOf:
- type: string
- type: 'null'
email:
anyOf:
- type: string
- type: 'null'
required:
- username
- email
additionalProperties: false
- type: 'null'
required:
- id
- title
- kind
- contentType
- extension
- bytes
- createdAt
- archived
- usedInRuns
- recommended
- createdBy
additionalProperties: false
required:
- document
additionalProperties: false
'400':
description: The request is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'401':
description: Missing or invalid bearer token
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'403':
description: The token lacks a scope, or its user lacks a permission
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'404':
description: Not found in the token organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'409':
description: The request conflicts with the current state
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'429':
description: Rate limited; see Retry-After
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
'503':
description: Temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorEnvelope'
components:
schemas:
ApiErrorEnvelope:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- invalid_request
- repository_required
- unauthenticated
- insufficient_credits
- spend_cap_reached
- insufficient_scope
- forbidden
- not_found
- repository_not_visible
- repository_not_added
- method_not_allowed
- position_unavailable
- decision_active
- conflict
- price_exceeds_max
- quote_stale
- change_refused
- nothing_to_review
- repository_not_runnable
- idempotency_key_reused
- api_version_retired
- payload_too_large
- unsupported_media_type
- rate_limited
- internal_error
- upstream_error
- platform_unavailable
- repository_access_unavailable
- rate_limit_unavailable
- public_api_disabled
message:
type: string
details:
type: object
propertyNames:
type: string
additionalProperties: {}
required:
- code
- message
additionalProperties: false
requestId:
type: string
required:
- error
- requestId
additionalProperties: false
securitySchemes:
bearer:
type: http
scheme: bearer
description: A personal access token (v12p_…) or an OAuth access token (v12a_…).
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://v12.sh/oauth/authorize
tokenUrl: https://v12.sh/api/oauth/token
refreshUrl: https://v12.sh/api/oauth/token
scopes:
user:read: 'The member directory: usernames, emails and roles. Any key reads its own account, organization and credit balance without it.'
repos:read: Repositories, branches, pull requests, tags and Steer instructions.
repos:write: Add public repositories to the workspace; owners can also add private repositories granted by GitHub, create repositories V12 hosts and push code to them.
steers:write: Create, edit, archive and restore Steers. Archiving detaches them from Autopilot rules; finding tags and run history are kept.
runs:read: Runs, their progress and context documents.
runs:write: Estimate and start runs; add or archive context documents.
runs:manage: Cancel runs.
runs:share: Create, change and revoke guest links that open a run to people outside the organization.
findings:read: 'The inbox: findings, their status, reports and comments.'
findings:write: Change status, comment and update triage decisions.