Agreebase exposes the same record model through several surfaces. Choose the surface by who is operating the workflow and whether the caller needs a direct HTTP contract or an agent-human ceremony.
Surface map
| Surface | Use it for | Entry point |
|---|---|---|
| Web app | Guided creation, signing, record management, and public verification | /create, /confirm/{agr_reference}, /my-records, /verify |
| REST API | Server-to-server and application integrations | /api/v1 |
| Hosted MCP connector | ChatGPT and Claude agent-human workflows with passwordless OAuth | /mcp/oauth |
| Direct/raw MCP | Public verification and explicitly configured credentials | /mcp |
| Public verification | Unauthenticated certificate and artifact checks | /api/v1/public or /verify |
| ChatGPT Action contract | ChatGPT-compatible HTTP integration | /api/v1/chatgpt-action-spec.yaml |
Machine-readable documentation is available at /api/openapi.json, /docs/catalog.json, /docs.md, and /llms.txt.
REST API
REST API base: /api/v1
MCP endpoints
MCP endpoint: /mcp
Use /mcp/oauth for ChatGPT and Claude hosted custom connectors. Adding the connector starts a standard OAuth flow: enter an email address, enter the six-digit authentication OTP, then choose Verify and connect. There are no accounts, passwords, registration forms, or API keys to copy. The host stores the OAuth tokens and refreshes the one-hour access token for up to 90 days from the original consent.
Use /mcp for direct or raw MCP clients. It retains unauthenticated public verification and accepts credentials that the operator explicitly configures on the transport. It does not use the hosted connector OAuth ceremony. Raw clients can inspect get_authentication_status and, when no transport credential is configured, use request_authentication_otp followed by verify_authentication_otp for the existing short-lived MCP session flow.
MCP clients should begin with the MCP quickstart, then use the MCP reference for the live tool contract, scope requirements, structured responses, and guarded lifecycle rules. Image-bearing REST and MCP response behavior, visibility, and share-card ticket handling are documented in the image-handling guide.
Start with the canonical references
- REST API reference covers endpoints, request shapes, responses, authentication, scopes, errors, and limits.
- MCP quickstart shows the streamable HTTP handshake and safe verification, authentication, creation, signing, and lifecycle sequences.
- MCP reference covers tool names, structured workflow responses, preview/execute safeguards, and human steps.
- Authentication and API keys covers OTP ceremonies, bearer tokens, API keys, identity linking, and scope boundaries.
- Image handling covers compact metadata, inline-image opt-ins, compatibility modes, identicon visibility, and single-use card URLs.
- Using Agreebase with agents covers safe orchestration rules rather than protocol schemas.
Shared product model
The record types are agreement, declaration, witnessed agreement, and notarization. All have an AGR reference, lifecycle status, participants, and sealing state. Agreements, declarations, and witnessed agreements store short normalized bodies. Notarizations store a client-supplied content identity and may not receive source file bytes.
Signatures are version-specific proof-of-control executions. A body change can invalidate current-version signature work. Sealed records are not edited in place; amendments and mutual cancellations create later records.
Safety boundary
REST is appropriate for application-controlled integrations. MCP is designed for an agent working with a human, so consequential lifecycle actions expose previews, consequence summaries, short-lived confirmation tokens, and exact retry actions. Do not put long-lived API keys in ordinary MCP tool arguments or chat.
The product contract is the generated OpenAPI schema, MCP tools/list output, and the public pages linked above. For MCP, the live tools/list response is the final authority for the focused discovery catalogue and its argument schemas, enums, annotations, and output schemas. Advanced lifecycle tools documented in the MCP reference remain callable by exact name even when omitted from initial discovery. Internal engineering documents and source paths are not required to use Agreebase.
MCP tools do not accept api_key as a normal tool argument. Protected failures use structured values such as missing_scope; see the MCP reference.
On /mcp/oauth, authentication is completed by the host before MCP initialization and get_authentication_status reports the OAuth principal. The authentication bootstrap tools remain in the shared schema for /mcp compatibility but are unnecessary for hosted connectors. Authentication only permits access to signature tools: signing still requires the separate, record/version-specific signature ceremony.