Commentary Tokens API
The Tokens API from Commentary — 2 operation(s) for tokens.
The Tokens API from Commentary — 2 operation(s) for tokens.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/commentary-dev:commentary-dev-tokens-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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: 3.2.0
info:
title: Commentary Dev Tokens API
version: 0.1.0
x-commentary-api-version: v1
x-commentary-compatibility-policy: /docs/api/versioning.md
x-commentary-feature-key: api.openapi_docs
description: 'Operations tagged Tokens across 2 of this provider''s published API definitions: commentary-dev-openapi.json, commentary-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://commentary.dev
description: Configured Commentary origin.
- url: http://localhost:3000
description: Local development.
tags:
- name: Tokens
paths:
/api/v1/tokens:
get:
operationId: listApiTokens
tags:
- Tokens
summary: List API tokens for the signed-in provider connection
security:
- commentarySession: []
x-commentary-feature-key: api.agent_access
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
required:
- ok
- tokens
properties:
ok:
const: true
tokens:
type: array
items:
$ref: '#/components/schemas/TokenSummary'
'400':
description: The request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'401':
description: Authentication is required.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'403':
description: The token or session does not have permission for this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'404':
description: The resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'429':
description: The request was rate limited.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
post:
operationId: createApiToken
tags:
- Tokens
summary: Create an API token for scripts, MCP clients, or agents
description: Issuance is atomic. Retry unchanged settings with the same Idempotency-Key after an uncertain outcome. Replay confirms the existing credential without returning its one-time secret; deliberately rotate it in Account Developer access for recovery.
security:
- commentarySession: []
parameters:
- in: header
name: Idempotency-Key
required: false
schema:
type: string
minLength: 1
maxLength: 200
description: Stable key for one issue. Omission preserves legacy non-idempotent requests.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTokenRequest'
x-commentary-feature-key: api.agent_access
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
required:
- ok
- id
- grantId
- tokenHint
properties:
ok:
const: true
id:
type: string
grantId:
type: string
replayed:
type: boolean
token:
type: string
description: One-time secret, present only for the original successful issue.
tokenHint:
type: string
'400':
description: The request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'401':
description: Authentication is required.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'403':
description: The token or session does not have permission for this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'404':
description: The resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'409':
description: The issuance key was reused with different settings or the connected account changed.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'429':
description: The request was rate limited.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
servers:
- url: https://commentary.dev
description: Configured Commentary origin.
- url: http://localhost:3000
description: Local development.
/api/v1/tokens/{tokenId}:
delete:
operationId: revokeApiToken
tags:
- Tokens
summary: Revoke an API token
security:
- commentarySession: []
parameters:
- name: tokenId
in: path
required: true
schema:
type: string
description: API token id.
x-commentary-feature-key: api.agent_access
responses:
'200':
description: Successful response.
content:
application/json:
schema:
type: object
required:
- ok
- id
properties:
ok:
const: true
id:
type: string
'400':
description: The request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'401':
description: Authentication is required.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'403':
description: The token or session does not have permission for this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'404':
description: The resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
'429':
description: The request was rate limited.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalError'
servers:
- url: https://commentary.dev
description: Configured Commentary origin.
- url: http://localhost:3000
description: Local development.
components:
schemas:
CreateTokenRequest:
type: object
properties:
label:
type: string
scopes:
oneOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/ExternalScope'
target:
$ref: '#/components/schemas/TokenTarget'
expiresAt:
type:
- string
- 'null'
format: date-time
additionalProperties: false
TokenTarget:
type: string
description: Target string such as account, github:owner/repo, github:owner/repo:pull:123, github:owner/repo:branch:main, or draft:sessionId.
ExternalError:
type: object
required:
- ok
- error
properties:
ok:
const: false
error:
type: string
additionalProperties: true
ExternalScope:
type: string
enum:
- commentary.review.settings.write
- commentary.agents.profile.write
- commentary.review.read
- commentary.comments.read
- commentary.comments.write
- commentary.comments.status
- commentary.review.share
- commentary.draft_reviews.delete
- commentary.draft_reviews.share
- commentary.review.submit
- commentary.forms.read
- commentary.forms.write
- commentary.forms.submit
- commentary.forms.writeback
- commentary.research.read
- commentary.research.write
- commentary.brain.evals.read
- commentary.brain.evals.write
- commentary.interactions.create
- commentary.interactions.read
- commentary.interactions.update
- commentary.interactions.cancel
- commentary.interactions.fulfillment
- commentary.inbox.read
- commentary.workspaces.read
- commentary.workspaces.resources.write
- commentary.webhooks.read
- commentary.webhooks.write
- commentary.projects.read
- commentary.projects.write
- commentary.trackers.read
- commentary.trackers.write
- commentary.trackers.writeback
- commentary.review_packages.read
- commentary.review_packages.write
- commentary.project_reviews.read
- commentary.project_reviews.write
- commentary.source_snapshots.read
- commentary.source_snapshots.write
- commentary.evidence.read
- commentary.evidence.write
- commentary.evidence.verify
TokenSummary:
type: object
properties:
id:
type: string
grantId:
type: string
tokenType:
type: string
tokenHint:
type: string
scopes:
type: array
items:
$ref: '#/components/schemas/ExternalScope'
resourceScope:
type: string
enum:
- review
- repo
- account
owner:
type:
- string
- 'null'
repo:
type:
- string
- 'null'
prNumber:
type:
- integer
- 'null'
branchRef:
type:
- string
- 'null'
draftReviewSessionId:
type:
- string
- 'null'
clientName:
type:
- string
- 'null'
expiresAt:
type:
- string
- 'null'
format: date-time
revokedAt:
type:
- string
- 'null'
format: date-time
lastUsedAt:
type:
- string
- 'null'
format: date-time
createdAt:
type: string
format: date-time
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Commentary external access token
description: Bearer token from an API token, OAuth authorization code flow, OAuth refresh token flow, or OAuth device flow.
commentarySession:
type: apiKey
in: cookie
name: commentary_session
description: Signed-in Commentary browser session. Used for API token management routes.
x-refined-from:
- commentary-dev-openapi.json
# --- truncated at 32 KB (485 KB total) ---
# Full source: https://artifacts.apis.io/commentary-dev/openapi/commentary-dev-tokens-api-openapi.yml