Published with v0.343.0
REST Agent Contract
The REST Agent Contract is the typed HTTP surface for advanced integrations. The checked-in OpenAPI 3.1 document is authoritative; its current independent contract version is 1.13.0. Use the production base URL https://mcp.atmina.ai and an OAuth bearer token delegated for that resource.
Operations
| Purpose | Method and path |
|---|---|
| Deployed version | GET /version |
Caller identity (includes own lens KBs as monitor) | GET /api/v1/whoami |
| List your MCP installations | GET /api/v1/account/mcp-connections |
| Activate a device installation | POST /api/v1/account/mcp-connections/activate |
| Revoke one installation | DELETE /api/v1/account/mcp-connections/{grant_id} |
| List or create KBs | GET or POST /api/v1/kbs |
| Resolve a Qualified KB Ref | GET /api/v1/kbs/by-ref/{team_slug}/{kb_slug} |
| Read or update one KB | GET or PATCH /api/v1/kbs/{id} |
| Exhaustively list files | GET /api/v1/kbs/{id}/files |
| Search one KB | POST /api/v1/kbs/{id}/search |
| Search accessible KBs | POST /api/v1/search |
| List models | GET /api/v1/models |
Anonymous published reads
Contract 1.13.0 adds getPublishedKnowledgeBase and
readPublishedKnowledgeBaseFile. Omit Authorization to read a published KB:
curl https://mcp.atmina.ai/api/v1/published-kbs/atmina-system/guide
curl --get https://mcp.atmina.ai/api/v1/published-kbs/atmina-system/guide/file \
--data-urlencode 'path=help/rest-agent-contract.md'
Use exactly one path or file_id query parameter. The server resolves it
directly, without a client-side catalog listing. Paths are decoded once and
matched exactly. The response contains file_id, path, filename, mime_type,
and content_base64. Its sha256 and size_bytes describe the returned UTF-8
public text after projection. The strong HTTP ETag hashes the entire serialized
JSON response. Responses use Cache-Control: no-store; conditional 304 is not
supported.
These two endpoints always return the current public representation, including when an owner supplies a valid token. Missing, private, shared, deleted, and malformed KB references have the same 404 response. Missing or excluded files also receive a neutral 404. Asset bytes are unavailable; a published Companion can be read at its own text path. Historical versions, image/rendition selectors, duplicate selectors, and unknown query parameters are rejected with 400.
A supplied Authorization header must be a valid bearer credential, even if a
browser cookie is also present. Empty, malformed, invalid, expired, or revoked
credentials receive 401 with an OAuth challenge. A valid bearer without
mcp:read receives 403. Published reads are rate limited; an unavailable live
public collection receives 503.
Use the detail response's kb_id with the existing searchKnowledgeBase
operation, POST /api/v1/kbs/{id}/search, and {"query":"memory"}. Anonymous
search uses keyword retrieval over the current public collection and removes
private metadata. It rejects filters, retrieval, ranking, and strict.
A valid independent KB grant searches that caller's authorized collection.
Supplied bearer tokens retain the POST scope requirement of both mcp:read and
mcp:write; invalid credentials fail rather than falling back to anonymous.
Search may return 401 or 403 for authentication or access failures, 429 for rate
limits, and 503 when the public collection is unavailable.
The existing listKnowledgeBaseFiles operation remains available when a catalog
listing is wanted. This contract addition does not publish file history, raw
Asset downloads, public graph operations, or additional mutations.
Governance and audit operations
Contract 1.11.0 published Team and Knowledge Base governance reads plus audit (LAT-2282 / LAT-1344). Authorization follows the Team admin / Team member / read-only lens (monitor) matrix: share inventory and Team audit stay admin-only; KB audit admits editor+ and an active lens on that Knowledge Base; /whoami includes the caller’s own lens KBs as monitor entries; Team status denies lenses; health and graph scope lenses to reachable or monitored Knowledge Bases; settings read and archived listing are admin-only.
Query text inside audit rows is retained only when the Team’s write-time audit_query_text setting was on when the event was recorded. Readers do not get a separate redaction operation.
| Purpose | Method and path |
|---|---|
| KB share inventory | GET /api/v1/kbs/{id}/share |
| Team share inventory | GET /api/v1/teams/{id}/shares |
| Team audit list | GET /api/v1/teams/{id}/audit |
| KB audit list | GET /api/v1/kbs/{id}/audit |
| Audit event detail | GET /api/v1/teams/{id}/audit/events/{event_id} |
| Team status | GET /api/v1/teams/{id}/status |
| Team health | GET /api/v1/teams/{id}/health |
| Team access graph | GET /api/v1/teams/{id}/graph |
| Team settings read | GET /api/v1/teams/{id}/settings |
| Archived Knowledge Bases | GET /api/v1/teams/{id}/archived-kbs |
Sharing and settings mutations
Contract 1.12.0 publishes sharing mutations and the Team settings update (LAT-2283 / LAT-1344). Only a Knowledge Base admin may share, revoke, or cancel: a Team admin of the owning Team, or an outside collaborator holding an admin grant on that Knowledge Base. Team members below admin and read-only lens holders are refused with 403. Only an admin of that Team may update its settings.
| Purpose | Method and path |
|---|---|
| Share a KB with a person, a Team, or an email address | POST /api/v1/kbs/{id}/share |
| Revoke one share grant | DELETE /api/v1/kbs/{id}/share/{grant_id} |
| Cancel a pending email invitation | DELETE /api/v1/kbs/{id}/share/pending/{invitation_id} |
| Update Team settings | PATCH /api/v1/teams/{id}/settings |
A share names exactly one target (target_user_id, target_team_id, or email) and exactly one access level: access of read, write, admin, or monitor, or the web alias role of viewer, editor, admin, or monitor. A read-only lens (monitor) can only go to one person; a Team or email lens is refused with 400. Sharing to the owning Team restores “Everyone in the team”; revoking that grant makes the Knowledge Base “Selected people” only.
Every mutation is safe to repeat. Revoking a grant that is already revoked returns revoked: false, cancelling an invitation that is already cancelled returns cancelled: false, and re-sending the current settings returns an empty changed list. Cancelling an invitation that was already accepted returns 409; revoke the resulting grant instead. A grant or invitation that belongs to a different Knowledge Base is 404.
Use Qualified KB Refs such as acme/handbook when resolving a human-readable identity. Every response is projected for the caller, so an inaccessible ref can look absent.
curl -sS https://mcp.atmina.ai/api/v1/kbs \
-H 'Authorization: Bearer <oauth-access-token>'
Search uses JSON and returns ranked, file-grouped results:
curl -sS https://mcp.atmina.ai/api/v1/kbs/<kb_id>/search \
-H 'Authorization: Bearer <oauth-access-token>' \
-H 'Content-Type: application/json' \
--data '{"query":"customer data retention decision","max_files":5}'
For the single-Knowledge Base route, the path already selects the Knowledge Base. Do not send scope.kb_ids or scope.kb_slugs. Either field produces a 400 validation_error; the message names the rejected selector and details.issues lists each rejected dotted path. Other scope filters, including path_prefix and file_ids, remain available.
MCP installation lifecycle
Contract 1.8.0 added the installation lifecycle operations. Each connection is a Delegated Grant for one client installation, so two installations of the same client can be revoked independently. Bearer requests require mcp:read; activation and revocation also require mcp:write.
List your installations with GET /api/v1/account/mcp-connections. The response contains a connections array, newest first, with each installation's grant_id, client name, scopes, status, and activity timestamps. Status is pending, active, revoked, or replaced. Listing and revoking accept an OAuth bearer token or an Account session cookie; they operate only on your own installations.
After device authorization returns its first bearer token, the client must call POST /api/v1/account/mcp-connections/activate with that token before using protected MCP or REST operations. This is the only route that accepts a pending installation. It returns { "grant": { ... }, "activated": true } when activation succeeds; repeating it for an already active grant returns activated: false. Browser-authorized installations are active immediately and do not need this step. A client should verify a protected read, such as GET /api/v1/whoami, before reporting a device connection as ready.
Revoke an installation by sending DELETE /api/v1/account/mcp-connections/{grant_id} with the ID from the list. A successful response is 204 with no body, including when that installation was already revoked. Its outstanding access tokens stop working and it cannot refresh them; your other installations keep their access. Another user's grant ID returns 404. You can also review and revoke these connections under Account → MCP connections.
Source and public content
Contract 1.9.0 adds public_collection to Knowledge Base configuration. Its folder_prefixes, include_sources, and include_consolidated fields let an owner explicitly widen the published collection. All additions default off. They change every public reading surface, including anonymous search, rather than granting search-only access. See Publish a Knowledge Base for the publication boundary.
Asset rows from GET /api/v1/kbs/{id}/files may include description_source: atmina assigns description ownership to Atmina, provider-native identifies a provider-owned conversion that cannot be read back or edited, and none means neither route describes the Asset. The field is absent from non-Asset rows and when provider context cannot be resolved. It does not confirm that generated text exists.
Search responses can add an asset object for picture results. Its path identifies the Asset while the result's own path and read_ref cite the Companion. Catalog-backed results may also include file_id, media facts, state and a thumbnail rendition_url; clients must accept the path-only form.
On the existing GET /api/v1/kbs/{id}/files/{file_id} endpoint, a public Companion read's content_base64 can contain the coordinate-safe public representation. representation.sha256 and representation.size_bytes identify those returned bytes; file.sha256 and file.size_bytes still identify the stored source. Do not use a projected-content digest as a source write precondition. Direct original-content downloads remain unavailable to public visitors; owning-Team members can download original Assets.
Safe mutations and recovery
For a retry-safe create, send a unique RFC 8941 Idempotency-Key of at most 128 decoded bytes and Atmina-Agent-Contract-Version: 1.13.0. Repeating the same completed request with that key returns the earlier logical result. Never reuse the key for different input.
Error-capable operations use { "error", "message", "details"? } as their fallback envelope, including failures whose status is not otherwise listed. A version conflict on an agent configuration update includes current_version and may include current. A rate-limit 429 uses { "error": "rate_limited", "retry_after_s", "scope" } and includes Retry-After; a credit-exhaustion 429 uses the fallback envelope and does not promise that header. Check error and schedule a retry from Retry-After only when the header is present.
A 401 includes a protected-resource challenge and requires a fresh OAuth grant. 403 means the authenticated caller lacks the operation's role. 404 can mean absent or deliberately hidden from this caller. Fix 400 input rather than retrying it.
For interactive clients, start with MCP authentication and connections.