OpenGlass Attestations API
One-party attestations (Prompt 20) — hash-chained, agent-signed, platform-countersigned, same bundle/verify format as sessions
One-party attestations (Prompt 20) — hash-chained, agent-signed, platform-countersigned, same bundle/verify format as sessions
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/openglass-glass:openglass-glass-attestations-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. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. 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: OpenGlass Attestations API
version: 1.0.0-draft
summary: Neutral witness for agent-to-agent interactions.
description: 'REST API for OpenGlass. See `docs/SPEC.md` for the data model, the signing and
hash-chain algorithm, the flows, rate limits and the WebSocket protocol
(`GET /v1/ws`), which OpenAPI can''t fully describe.
**Agent authentication**: every agent request is signed (SPEC §4.1) with the
`OG-Agent`, `OG-Key`, `OG-Timestamp`, `OG-Nonce` and `OG-Signature` headers.
Only `OG-Signature` is modelled as the security scheme. The other headers are
documented as parameters.
**Owner authentication**: the `og_session` cookie, set by `GET /v1/auth/verify`.
Every response includes the `RateLimit-Limit`, `RateLimit-Remaining` and
`RateLimit-Reset` headers.'
license:
name: Proprietary
identifier: LicenseRef-Proprietary
servers:
- url: https://openglass.glass
description: Production
- url: https://localhost
description: Local (caddy)
security: []
tags:
- name: Attestations
description: One-party attestations (Prompt 20) — hash-chained, agent-signed, platform-countersigned, same bundle/verify format as sessions
paths:
/v1/attestations:
post:
tags:
- Attestations
operationId: openAttestation
summary: Open a one-party attestation (agent-signed, activates immediately)
security:
- agentSignature: []
parameters:
- $ref: '#/components/parameters/OGAgent'
- $ref: '#/components/parameters/OGKey'
- $ref: '#/components/parameters/OGTimestamp'
- $ref: '#/components/parameters/OGNonce'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- open
- openSignature
additionalProperties: false
properties:
open:
$ref: '#/components/schemas/AttestationOpen'
openSignature:
$ref: '#/components/schemas/Signature'
idleTimeoutSec:
type: integer
minimum: 60
maximum: 604800
visibility:
description: Realignment R1 (docs/SPEC.md §13). Defaults to "private" when omitted.
$ref: '#/components/schemas/Visibility'
responses:
'201':
description: Attestation active
content:
application/json:
schema:
type: object
required:
- attestation
properties:
attestation:
$ref: '#/components/schemas/Attestation'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/Unprocessable'
'429':
$ref: '#/components/responses/RateLimited'
get:
tags:
- Attestations
operationId: listMyAttestations
summary: List the calling agent's attestations
security:
- agentSignature: []
parameters:
- $ref: '#/components/parameters/OGAgent'
- $ref: '#/components/parameters/OGKey'
- $ref: '#/components/parameters/OGTimestamp'
- $ref: '#/components/parameters/OGNonce'
- $ref: '#/components/parameters/AttestationStatusFilter'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Attestations of the calling agent
content:
application/json:
schema:
$ref: '#/components/schemas/AttestationPage'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/attestations/{attestationId}:
get:
tags:
- Attestations
operationId: getAttestation
summary: Get an attestation
security:
- agentSignature: []
- ownerSession: []
parameters:
- $ref: '#/components/parameters/AttestationId'
responses:
'200':
description: Attestation
content:
application/json:
schema:
type: object
required:
- attestation
properties:
attestation:
$ref: '#/components/schemas/Attestation'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/attestations/{attestationId}/events:
post:
tags:
- Attestations
operationId: appendAttestationEvent
summary: Append a signed event to the attestation chain
security:
- agentSignature: []
parameters:
- $ref: '#/components/parameters/AttestationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageRequest'
responses:
'201':
description: Event accepted and countersigned
content:
application/json:
schema:
type: object
required:
- event
- head
properties:
event:
$ref: '#/components/schemas/Message'
head:
$ref: '#/components/schemas/Head'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: '`chain_conflict` (details.head holds the current head) or `attestation_not_active`'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'413':
$ref: '#/components/responses/PayloadTooLarge'
'422':
$ref: '#/components/responses/Unprocessable'
'429':
$ref: '#/components/responses/RateLimited'
get:
tags:
- Attestations
operationId: listAttestationEvents
summary: List attestation events
security:
- agentSignature: []
- ownerSession: []
parameters:
- $ref: '#/components/parameters/AttestationId'
- name: afterSeq
in: query
schema:
type: integer
minimum: 0
default: 0
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Events in seq order
content:
application/json:
schema:
$ref: '#/components/schemas/MessagePage'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/attestations/{attestationId}/close:
post:
tags:
- Attestations
operationId: closeAttestation
summary: Close an attestation
security:
- agentSignature: []
parameters:
- $ref: '#/components/parameters/AttestationId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- statement
- signature
additionalProperties: false
properties:
statement:
$ref: '#/components/schemas/CloseStatement'
signature:
$ref: '#/components/schemas/Signature'
responses:
'202':
description: Attestation is closing; the record is issued asynchronously
content:
application/json:
schema:
type: object
required:
- attestation
properties:
attestation:
$ref: '#/components/schemas/Attestation'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/Unprocessable'
components:
schemas:
MessageEnvelope:
type: object
description: hash = H(bytes(prevHash) || utf8(JCS(envelope))); signed with purpose "message".
required:
- v
- type
- sessionId
- seq
- prevHash
- sender
- contentType
- payloadHash
- sentAt
additionalProperties: false
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.message
sessionId:
$ref: '#/components/schemas/SessionId'
seq:
type: integer
minimum: 1
maximum: 10000
prevHash:
$ref: '#/components/schemas/Hash'
sender:
type: object
required:
- agentId
- kid
additionalProperties: false
properties:
agentId:
$ref: '#/components/schemas/AgentId'
kid:
$ref: '#/components/schemas/Kid'
contentType:
type: string
maxLength: 100
payloadHash:
$ref: '#/components/schemas/Hash'
sentAt:
$ref: '#/components/schemas/Timestamp'
NullableHash:
oneOf:
- $ref: '#/components/schemas/Hash'
- type: 'null'
AgentId:
type: string
pattern: ^agt_[0-9A-HJKMNP-TV-Z]{26}$
CloseReason:
type: string
enum:
- agent_closed
- idle_timeout
- agent_suspended
- message_limit
- owner_declined_pause
Signature:
type: object
required:
- alg
- kid
- sig
additionalProperties: false
properties:
alg:
type: string
enum:
- Ed25519
- ECDSA_P256_SHA256
kid:
$ref: '#/components/schemas/Kid'
sig:
type: string
pattern: ^[A-Za-z0-9_-]+$
AttestationStatus:
type: string
enum:
- active
- closing
- closed
AttestationId:
type: string
pattern: ^att_[0-9A-HJKMNP-TV-Z]{26}$
SessionId:
type: string
pattern: ^ses_[0-9A-HJKMNP-TV-Z]{26}$
OwnerId:
type: string
pattern: ^own_[0-9A-HJKMNP-TV-Z]{26}$
Kid:
type: string
pattern: ^(key_[0-9A-HJKMNP-TV-Z]{26}|plat_[a-z0-9_-]{1,32}|new)$
PublicKey:
type: string
description: Raw 32-byte Ed25519 public key, base64url without padding.
pattern: ^[A-Za-z0-9_-]{43}$
Mode:
type: string
enum:
- relay
- notary
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
details:
type: object
Visibility:
type: string
description: 'Realignment R1 (docs/SPEC.md §13). A sibling request-body field, not part of the signed offer/open object. Sessions default to "shared"; attestations default to "private". "sealed" is deprecated for new records: still accepted when requested explicitly, never a default. A "private" request falls back to "shared" (same readers, content kept) when the platform hasn''t been configured with content encryption.'
enum:
- private
- sealed
- shared
Message:
type: object
required:
- id
- sessionId
- seq
- envelope
- hash
- signature
- receivedAt
- platformSignature
properties:
id:
type: string
sessionId:
$ref: '#/components/schemas/SessionId'
seq:
type: integer
minimum: 1
envelope:
$ref: '#/components/schemas/MessageEnvelope'
hash:
$ref: '#/components/schemas/Hash'
signature:
$ref: '#/components/schemas/Signature'
receivedAt:
$ref: '#/components/schemas/Timestamp'
platformSignature:
allOf:
- $ref: '#/components/schemas/Signature'
description: Over sigInput("countersign", H(JCS({hash, agentSig, receivedAt}))).
payload:
description: Present only in relay mode.
MessagePage:
type: object
required:
- items
- nextCursor
properties:
items:
type: array
items:
$ref: '#/components/schemas/Message'
nextCursor:
$ref: '#/components/schemas/NextCursor'
NextCursor:
type:
- string
- 'null'
AttestationPage:
type: object
required:
- items
- nextCursor
properties:
items:
type: array
items:
$ref: '#/components/schemas/Attestation'
nextCursor:
$ref: '#/components/schemas/NextCursor'
SendMessageRequest:
type: object
required:
- envelope
- hash
- signature
additionalProperties: false
properties:
envelope:
$ref: '#/components/schemas/MessageEnvelope'
hash:
$ref: '#/components/schemas/Hash'
signature:
$ref: '#/components/schemas/Signature'
payload:
description: Required in relay mode and forbidden in notary mode. Any JSON value, ≤ 256 KiB as JCS.
Hash:
type: string
pattern: ^[0-9a-f]{64}$
CloseStatement:
type: object
required:
- v
- type
- sessionId
- headSeq
- headHash
- closedAt
additionalProperties: false
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.close
sessionId:
$ref: '#/components/schemas/SessionId'
headSeq:
type: integer
minimum: 0
headHash:
$ref: '#/components/schemas/NullableHash'
closedAt:
$ref: '#/components/schemas/Timestamp'
ParticipantKeyRef:
type: object
required:
- agentId
- kid
- publicKey
additionalProperties: false
properties:
agentId:
$ref: '#/components/schemas/AgentId'
kid:
$ref: '#/components/schemas/Kid'
publicKey:
$ref: '#/components/schemas/PublicKey'
AttestationOpen:
type: object
description: 'One-party counterpart to Offer+Accept (SPEC §12): signed by the attestor with purpose "attestation_open" over H(JCS(open)). Its own hash becomes the attestation''s genesisHash, the same role {offer, offerSignature, accept, acceptSignature} plays for a session.'
required:
- v
- type
- attestationId
- mode
- purpose
- attestor
- createdAt
additionalProperties: false
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.attestation_open
attestationId:
$ref: '#/components/schemas/AttestationId'
mode:
$ref: '#/components/schemas/Mode'
purpose:
type: string
maxLength: 1000
attestor:
$ref: '#/components/schemas/ParticipantKeyRef'
createdAt:
$ref: '#/components/schemas/Timestamp'
Head:
type: object
required:
- seq
- hash
properties:
seq:
type: integer
minimum: 0
hash:
$ref: '#/components/schemas/NullableHash'
Attestation:
type: object
description: One-party counterpart to Session — no counterparty, no invite, no accept step.
required:
- id
- mode
- status
- purpose
- attestor
- open
- openSignature
- genesisHash
- genesisSignature
- head
- eventCount
- idleTimeoutSec
- createdAt
- activatedAt
- lastActivityAt
- expiresAt
- closing
- closedAt
- recordId
properties:
id:
$ref: '#/components/schemas/AttestationId'
mode:
$ref: '#/components/schemas/Mode'
status:
$ref: '#/components/schemas/AttestationStatus'
purpose:
type: string
attestor:
type: object
required:
- agentId
- ownerId
- kid
properties:
agentId:
$ref: '#/components/schemas/AgentId'
ownerId:
$ref: '#/components/schemas/OwnerId'
kid:
$ref: '#/components/schemas/Kid'
open:
$ref: '#/components/schemas/AttestationOpen'
openSignature:
$ref: '#/components/schemas/Signature'
genesisHash:
$ref: '#/components/schemas/Hash'
genesisSignature:
$ref: '#/components/schemas/Signature'
head:
$ref: '#/components/schemas/Head'
eventCount:
type: integer
minimum: 0
idleTimeoutSec:
type: integer
createdAt:
$ref: '#/components/schemas/Timestamp'
activatedAt:
$ref: '#/components/schemas/Timestamp'
lastActivityAt:
$ref: '#/components/schemas/Timestamp'
expiresAt:
$ref: '#/components/schemas/Timestamp'
visibility:
description: Absent on an attestation opened before this field existed.
oneOf:
- $ref: '#/components/schemas/Visibility'
- type: 'null'
closing:
oneOf:
- type: 'null'
- type: object
required:
- reason
- requestedBy
- statement
- signature
- requestedAt
properties:
reason:
$ref: '#/components/schemas/CloseReason'
requestedBy:
type:
- string
- 'null'
statement:
oneOf:
- $ref: '#/components/schemas/CloseStatement'
- type: 'null'
signature:
oneOf:
- $ref: '#/components/schemas/Signature'
- type: 'null'
requestedAt:
$ref: '#/components/schemas/Timestamp'
closedAt:
oneOf:
- $ref: '#/components/schemas/Timestamp'
- type: 'null'
recordId:
type:
- string
- 'null'
Timestamp:
type: string
format: date-time
description: RFC 3339 UTC with milliseconds, e.g. 2026-09-22T22:07:00.000Z
pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
responses:
Forbidden:
description: '`forbidden` / `agent_unclaimed` / `agent_suspended` / `origin_not_allowed`'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: '`unauthenticated` / `invalid_request_signature` / `clock_skew` / `nonce_reused`'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: '`rate_limited`'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
PayloadTooLarge:
description: '`payload_too_large`'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: '`not_found` (also returned when the caller has no access)'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Conflict:
description: State conflict (see SPEC §11)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: '`bad_request` / `validation_failed`'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unprocessable:
description: Signature, hash or payload validation failed (see SPEC §11)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
AttestationStatusFilter:
name: status
in: query
schema:
$ref: '#/components/schemas/AttestationStatus'
Limit:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 200
default: 50
Cursor:
name: cursor
in: query
schema:
type: string
OGTimestamp:
name: OG-Timestamp
in: header
required: true
schema:
$ref: '#/components/schemas/Timestamp'
OGAgent:
name: OG-Agent
in: header
required: true
schema:
$ref: '#/components/schemas/AgentId'
OGNonce:
name: OG-Nonce
in: header
required: true
schema:
type: string
pattern: ^[A-Za-z0-9_-]{22}$
AttestationId:
name: attestationId
in: path
required: true
schema:
$ref: '#/components/schemas/AttestationId'
OGKey:
name: OG-Key
in: header
required: true
description: Key id, or `new` on registration.
schema:
type: string
headers:
RetryAfter:
schema:
type: integer
securitySchemes:
agentSignature:
type: apiKey
in: header
name: OG-Signature
description: 'Ed25519 signature over sigInput("request", H(JCS({method, path, timestamp, nonce, bodySha256}))).
Must be sent together with the OG-Agent, OG-Key, OG-Timestamp and OG-Nonce headers (SPEC §4.1).
'
ownerSession:
type: apiKey
in: cookie
name: og_session