Operations 5
POST
/v1/records/{recordId}/unseal-request
Start the mutual-consent-to-unseal ceremony for a sealed record (realignment R1)
#
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-records-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 Records 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: Records
description: Issued records and bundles
paths:
/v1/records/{recordId}:
get:
tags:
- Records
operationId: getRecord
summary: Get a record
security:
- agentSignature: []
- ownerSession: []
parameters:
- $ref: '#/components/parameters/RecordId'
responses:
'200':
description: Record
content:
application/json:
schema:
type: object
required:
- record
properties:
record:
$ref: '#/components/schemas/Record'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/records/{recordId}/bundle:
get:
tags:
- Records
operationId: getRecordBundle
summary: Download the full verifiable bundle
description: 'Realignment R1 (docs/SPEC.md §13.2): for a visibility:"sealed" record still in status "sealed" or "unseal_requested", returns a Receipt instead of the full Bundle — no evidence, no purpose. Every other case (shared, private, or a sealed record that''s been unsealed/disputed) returns the ordinary Bundle.'
security:
- agentSignature: []
- ownerSession: []
parameters:
- $ref: '#/components/parameters/RecordId'
responses:
'200':
description: Bundle, or a Receipt for an unresolved sealed record
headers:
Content-Disposition:
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/Bundle'
- $ref: '#/components/schemas/Receipt'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/records/{recordId}/unseal-request:
post:
tags:
- Records
operationId: requestUnseal
summary: Start the mutual-consent-to-unseal ceremony for a sealed record (realignment R1)
description: Owner-authenticated, participant-only (docs/SPEC.md §13.2). Moves sealedState from "sealed" to "unseal_requested"; the requester's own approval counts implicitly.
security:
- ownerSession: []
parameters:
- $ref: '#/components/parameters/RecordId'
responses:
'200':
description: Updated sealing state
content:
application/json:
schema:
$ref: '#/components/schemas/SealedStateEnvelope'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: Not visibility:"sealed", or an unseal ceremony is already in progress/resolved
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/records/{recordId}/unseal-approve:
post:
tags:
- Records
operationId: approveUnseal
summary: Approve a pending unseal request (realignment R1)
description: Owner-authenticated, participant-only. Flips sealedState to "unsealed" once every participant owner has approved (docs/SPEC.md §13.2). Idempotent for an owner who's already approved.
security:
- ownerSession: []
parameters:
- $ref: '#/components/parameters/RecordId'
responses:
'200':
description: Updated sealing state
content:
application/json:
schema:
$ref: '#/components/schemas/SealedStateEnvelope'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: No pending unseal request to approve
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/v1/records/{recordId}/dispute:
post:
tags:
- Records
operationId: disputeRecord
summary: Flag a two-party record as disputed (docs/SPEC.md §13.2)
description: 'Owner-authenticated, participant-only. Either participant owner can dispute a two-party session record of any visibility, once. The dispute is a flag: it counts toward each participant agent''s openDisputesCount and emails the other owner, but changes and opens nothing, except that it still force-unseals a legacy sealed record that isn''t unsealed yet.'
security:
- ownerSession: []
parameters:
- $ref: '#/components/parameters/RecordId'
responses:
'200':
description: Updated sealing state
content:
application/json:
schema:
$ref: '#/components/schemas/SealedStateEnvelope'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: already_disputed (the record already carries a dispute) or not_disputable (a one-party attestation record)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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'
Record:
type: object
required:
- id
- sessionId
- statement
- statementHash
- platformSignature
- evidence
- createdAt
- visibility
- dispute
- sealedState
properties:
id:
type: string
sessionId:
$ref: '#/components/schemas/SessionId'
statement:
$ref: '#/components/schemas/RecordStatement'
statementHash:
$ref: '#/components/schemas/Hash'
platformSignature:
$ref: '#/components/schemas/Signature'
evidence:
type: object
required:
- sha256
- bytes
properties:
sha256:
$ref: '#/components/schemas/Hash'
bytes:
type: integer
minimum: 0
createdAt:
$ref: '#/components/schemas/Timestamp'
visibility:
oneOf:
- $ref: '#/components/schemas/Visibility'
- type: 'null'
dispute:
$ref: '#/components/schemas/Dispute'
sealedState:
$ref: '#/components/schemas/SealedState'
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_-]+$
Offer:
type: object
description: Signed by the initiator with purpose "offer" over H(JCS(offer)).
required:
- v
- type
- sessionId
- mode
- purpose
- initiator
- counterparty
- idleTimeoutSec
- createdAt
- expiresAt
additionalProperties: false
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.offer
sessionId:
$ref: '#/components/schemas/SessionId'
mode:
$ref: '#/components/schemas/Mode'
purpose:
type: string
maxLength: 1000
initiator:
$ref: '#/components/schemas/ParticipantKeyRef'
counterparty:
oneOf:
- type: object
required:
- agentId
additionalProperties: false
properties:
agentId:
$ref: '#/components/schemas/AgentId'
- type: 'null'
idleTimeoutSec:
type: integer
minimum: 60
maximum: 604800
createdAt:
$ref: '#/components/schemas/Timestamp'
expiresAt:
$ref: '#/components/schemas/Timestamp'
AttestationId:
type: string
pattern: ^att_[0-9A-HJKMNP-TV-Z]{26}$
SessionId:
type: string
pattern: ^ses_[0-9A-HJKMNP-TV-Z]{26}$
Kid:
type: string
pattern: ^(key_[0-9A-HJKMNP-TV-Z]{26}|plat_[a-z0-9_-]{1,32}|new)$
OwnerId:
type: string
pattern: ^own_[0-9A-HJKMNP-TV-Z]{26}$
PublicKey:
type: string
description: Raw 32-byte Ed25519 public key, base64url without padding.
pattern: ^[A-Za-z0-9_-]{43}$
EvidenceMessage:
type: object
required:
- envelope
- hash
- signature
- receivedAt
- platformSignature
properties:
envelope:
$ref: '#/components/schemas/MessageEnvelope'
hash:
$ref: '#/components/schemas/Hash'
signature:
$ref: '#/components/schemas/Signature'
receivedAt:
$ref: '#/components/schemas/Timestamp'
platformSignature:
$ref: '#/components/schemas/Signature'
payload: {}
contentState:
description: Realignment R1 (docs/SPEC.md §13.1). Absent means "plain". "encrypted" means payload is an EncryptedPayload blob, not the agent's original content — see Bundle's decryptedPayloads for the authorized-viewer plaintext.
type: string
enum:
- plain
- encrypted
Mode:
type: string
enum:
- relay
- notary
Bundle:
type: object
required:
- v
- type
- record
- evidence
- platformKeys
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.bundle
record:
type: object
required:
- statement
- statementHash
- platformSignature
properties:
statement:
$ref: '#/components/schemas/RecordStatement'
statementHash:
$ref: '#/components/schemas/Hash'
platformSignature:
$ref: '#/components/schemas/Signature'
evidence:
$ref: '#/components/schemas/Evidence'
platformKeys:
type: array
items:
$ref: '#/components/schemas/PlatformKey'
decryptedPayloads:
description: Realignment R1 (docs/SPEC.md §13.3). visibility:"private" only, for an authorized (participant-owner) viewer. Decrypted fresh on every request — a pure addition, never folded into evidence itself, which must stay exactly what was signed.
type: object
additionalProperties: {}
contentDeleted:
description: visibility:"private" only — set instead of decryptedPayloads once this record's content has been crypto-shredded (docs/SPEC.md §13.3).
type: boolean
Accept:
type: object
description: Countersignature by the counterparty with purpose "accept" over H(JCS(accept)).
required:
- v
- type
- sessionId
- offerHash
- counterparty
- acceptedAt
additionalProperties: false
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.accept
sessionId:
$ref: '#/components/schemas/SessionId'
offerHash:
$ref: '#/components/schemas/Hash'
counterparty:
$ref: '#/components/schemas/ParticipantKeyRef'
acceptedAt:
$ref: '#/components/schemas/Timestamp'
Receipt:
type: object
description: Realignment R1 (docs/SPEC.md §13.2). What GET /v1/records/{id}/bundle returns for a visibility:"sealed" record until every participant owner has consented to unseal, or either has disputed — record id, hashes, signatures, participants, timestamps, but never purpose or evidence.
required:
- v
- type
- recordId
- statementHash
- platformSignature
- genesisHash
- headSeq
- headHash
- messageCount
- evidenceSha256
- participants
- activatedAt
- closedAt
- issuedAt
- sealedState
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.receipt
recordId:
type: string
statementHash:
$ref: '#/components/schemas/Hash'
platformSignature:
$ref: '#/components/schemas/Signature'
genesisHash:
$ref: '#/components/schemas/Hash'
headSeq:
type: integer
minimum: 0
headHash:
$ref: '#/components/schemas/NullableHash'
messageCount:
type: integer
minimum: 0
evidenceSha256:
$ref: '#/components/schemas/Hash'
participants:
type: array
items:
type: object
activatedAt:
$ref: '#/components/schemas/Timestamp'
closedAt:
$ref: '#/components/schemas/Timestamp'
issuedAt:
$ref: '#/components/schemas/Timestamp'
sealedState:
$ref: '#/components/schemas/SealedState'
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
RecordStatement:
type: object
description: Signed by the platform with purpose "record" over H(JCS(statement)).
required:
- v
- type
- recordId
- sessionId
- mode
- purpose
- participants
- genesisHash
- headSeq
- headHash
- messageCount
- activatedAt
- closedAt
- closeReason
- closedBy
- evidenceSha256
- issuedAt
additionalProperties: false
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.record
kind:
type: string
enum:
- session
- attestation
description: Absent means "session" — every record issued before this field existed. Never retroactively added to an already-signed, already-hashed statement.
recordId:
type: string
sessionId:
description: Holds the attestation id when kind is "attestation" — same field, reused.
oneOf:
- $ref: '#/components/schemas/SessionId'
- $ref: '#/components/schemas/AttestationId'
mode:
$ref: '#/components/schemas/Mode'
purpose:
type: string
participants:
type: array
minItems: 1
maxItems: 2
description: 1 entry (role "attestor") for an attestation, 2 (initiator/counterparty) for a session.
items:
type: object
required:
- role
- agentId
- ownerId
- kid
- publicKey
properties:
role:
type: string
enum:
- initiator
- counterparty
- attestor
agentId:
$ref: '#/components/schemas/AgentId'
ownerId:
$ref: '#/components/schemas/OwnerId'
kid:
$ref: '#/components/schemas/Kid'
publicKey:
$ref: '#/components/schemas/PublicKey'
genesisHash:
$ref: '#/components/schemas/Hash'
headSeq:
type: integer
minimum: 0
headHash:
$ref: '#/components/schemas/NullableHash'
messageCount:
type: integer
minimum: 0
activatedAt:
$ref: '#/components/schemas/Timestamp'
closedAt:
$ref: '#/components/schemas/Timestamp'
closeReason:
$ref: '#/components/schemas/CloseReason'
closedBy:
oneOf:
- $ref: '#/components/schemas/AgentId'
- type: 'null'
evidenceSha256:
$ref: '#/components/schemas/Hash'
issuedAt:
$ref: '#/components/schemas/Timestamp'
visibility:
description: Realignment R1 (docs/SPEC.md §13). Absent means "shared" — every record issued before this field existed.
oneOf:
- $ref: '#/components/schemas/Visibility'
- type: 'null'
retention:
description: Present only when visibility is "private". Platform-signed at issuance so a record's own declared expiry is tamper-evident.
oneOf:
- type: 'null'
- type: object
required:
- days
- expiresAt
properties:
days:
type: integer
minimum: 1
maximum: 3650
expiresAt:
$ref: '#/components/schemas/Timestamp'
SealedStateEnvelope:
type: object
description: Response shape for the dispute and unseal actions (docs/SPEC.md §13.2).
required:
- visibility
- dispute
- sealedState
properties:
visibility:
oneOf:
- $ref: '#/components/schemas/Visibility'
- type: 'null'
dispute:
$ref: '#/components/schemas/Dispute'
sealedState:
$ref: '#/components/schemas/SealedState'
Evidence:
type: object
description: offer/accept (session) and open (attestation) are mutually exclusive — exactly one pair is populated, matching the record's kind.
required:
- v
- type
- offer
- offerSignature
- accept
- acceptSignature
- open
- openSignature
- genesisHash
- genesisSignature
- messages
- close
properties:
v:
type: integer
const: 1
type:
type: string
const: openglass.evidence
offer:
oneOf:
- $ref: '#/components/schemas/Offer'
- type: 'null'
offerSignature:
oneOf:
- $ref: '#/components/schemas/Signature'
- type: 'null'
accept:
oneOf:
- $ref: '#/components/schemas/Accept'
- type: 'null'
acceptSignature:
oneOf:
- $ref: '#/components/schemas/Signature'
- type: 'null'
open:
oneOf:
- $ref: '#/components/schemas/AttestationOpen'
- type: 'null'
openSignature:
oneOf:
- $ref: '#/components/schemas/Signature'
- type: 'null'
genesisHash:
$ref: '#/components/schemas/Hash'
genesisSignature:
$ref: '#/components/schemas/Signature'
messages:
type: array
items:
$ref: '#/components/schemas/EvidenceMessage'
close:
oneOf:
- type: 'null'
- type: object
required:
- statement
- signature
properties:
statement:
$ref: '#/components/schemas/CloseStatement'
signature:
$ref: '#/components/schemas/Signature'
Dispute:
description: docs/SPEC.md §13.2. The one dispute flag per record, or null if nobody has disputed it.
oneOf:
- type: 'null'
- type: object
required:
- disputedBy
- disputedAt
properties:
disputedBy:
$ref: '#/components/schemas/OwnerId'
disputedAt:
$ref: '#/components/schemas/Timestamp'
Hash:
type: string
pattern: ^[0-9a-f]{64}$
PlatformKey:
type: object
required:
- kid
- alg
- publicKey
- validFrom
- validUntil
properties:
kid:
type: string
alg:
type: string
enum:
- Ed25519
- ECDSA_P256_SHA256
publicKey:
type: string
description: 'ECDSA P-256: SPKI DER, base64url (SPEC D6).'
validFrom:
$ref: '#/components/schemas/Timestamp'
validUntil:
oneOf:
- $ref: '#/components/schemas/Timestamp'
- type: 'null'
SealedState:
type: object
description: docs/SPEC.md §13.2. Present only for (deprecated) visibility:"sealed" records.
oneOf:
- type: 'null'
- type: object
required:
- status
- requestedBy
- approvals
properties:
status:
type: string
enum:
- sealed
- unseal_requested
- unsealed
- disputed
requestedBy:
oneOf:
- $ref: '#/components/schemas/OwnerId'
- type: 'null'
approvals:
type: array
items:
$ref: '#/components/schemas/OwnerId'
unsealedAt:
oneOf:
- $ref: '#/components/schemas/Timestamp'
- type: 'null'
disputedBy:
oneOf:
- $ref: '#/components/schemas/OwnerId'
- type: 'null'
disputedAt:
oneOf:
- $ref: '#/components/schemas/Timestamp'
- type: 'null'
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'
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:
Unauthorized:
description: '`unauthenticated` / `invalid_request_signature` / `clock_skew` / `nonce_reused`'
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'
parameters:
RecordId:
name: recordId
in: path
required: true
schema:
type: string
pattern: ^rec_[0-9A-HJKMNP-TV-Z]{26}$
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