API Reference

The Modei REST API. Base URL: https://modei.ai/api/v1. Authenticated with API keys (format: mod_...).

··

Base URL

text

https://modei.ai/api/v1

Authentication

All API requests require an API key in the Authorization header:

bash

curl https://modei.ai/api/v1/passports \
  -H "Authorization: Bearer mod_live_xxxxxxxx"

Generate API keys from Dashboard → Settings → API Keys. Keys have scopes, only grant what's needed. Never hardcode keys; use environment variables.

API Key Scopes

Scope	Allows
passports:issue	Create new passports
passports:read	Read passport details and status
passports:revoke	Revoke passports
gates:create	Create new gates
gates:read	Read gate configuration
gates:update	Modify gate rules
gates:manage	Full gate administration
issuers:create	Create new issuers
issuers:read	Read issuer details
issuers:update	Modify issuers
templates:read	Read templates
templates:create	Create custom templates
osgate:read	Read OS Gate session data
osgate:manage	Full OS Gate management
admin:*	Full admin access (use carefully)

Rate Limits

Tier	Requests/minute	Requests/day
Free	30	1,000
Pro	120	10,000
Teams	300	50,000
Enterprise	Custom	Custom

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Error Format

Error Response

{
  "error": {
    "code": "passport_not_found",
    "message": "Passport pass_01HABC... does not exist",
    "status": 404,
    "request_id": "req_01HXYZ..."
  }
}

Status	Meaning
200	Success
201	Created
400	Bad request, check your payload
401	Missing or invalid API key
403	Insufficient API key scope
404	Resource not found
409	Conflict (e.g., duplicate agent_id)
429	Rate limited, slow down
500	Server error, contact support

Endpoint Index

text

# Issuers
POST   /issuers                      Create an issuer
GET    /issuers                      List issuers
GET    /issuers/:id                  Get issuer

# Passports
POST   /passports                    Issue a passport
GET    /passports                    List passports
GET    /passports/:id                Get passport
POST   /passports/:id/revoke         Revoke a passport
GET    /passports/:id/verify         Verify passport validity

# Gates
POST   /gates                        Create a gate
GET    /gates                        List gates
GET    /gates/:id                    Get gate
PUT    /gates/:id                    Update gate
DELETE /gates/:id                    Delete gate
POST   /gates/:id/test               Test a gate

# Attestations
GET    /attestations                 List attestations
GET    /attestations/:id             Get single attestation
GET    /attestations/export          Export audit trail (JSON/CSV)

# Templates
GET    /templates                    List templates
GET    /templates/:id                Get template
POST   /templates                    Create custom template

Webhooks

Subscribe to real-time events from the dashboard → Settings → Webhooks.

Webhook Payload Example

{
  "event": "passport.verified",
  "timestamp": "2026-02-24T14:30:00Z",
  "data": {
    "passport_id": "pass_01HXYZ...",
    "agent_id": "my-agent-001",
    "gate_id": "gate_01HABC...",
    "decision": "allow",
    "attestation_id": "att_01HDEF..."
  }
}

Available events: passport.verified, passport.denied, passport.revoked, gate.created, spend_limit.approaching

API Sub-References

Passports API

Issue, list, get, revoke. Full request/response examples.

Gates API

Create, list, get, update, verify. Full examples.

Issuers API

Create, list, get, update.

Audit Trail API

Attestation endpoints, filtering, exporting.

Python SDK API — Passports