Projects & Keys

A project is a tenant: an isolated knowledge base plus its API keys. These endpoints use the admin credential.

Create a project

POST /v1/projects

Body

Field	Type	Notes
`name`	string	required, 1–255 chars
`ontology`	string	optional, defaults to `default` — see Ontologies

curl -X POST https://api.your-host/v1/projects \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "partner-acme", "ontology": "default"}'

Response 201

{ "id": "a40ccdf2-…", "name": "partner-acme", "api_key": "grag_…", "created_at": "2026-08-15T…Z" }

The api_key is shown once. Store it securely; it cannot be retrieved again — only rotated.

Issue an additional key

POST /v1/projects/{id}/keys

Field	Type	Notes
`name`	string	optional label
`expires_in_days`	integer	optional, 1–3650; omit for a non-expiring key

Returns { id, api_key, name, prefix, expires_at, created_at } — the raw api_key once only.

List keys

GET /v1/projects/{id}/keys

Returns each key’s identity and lifecycle — never the secret:

[{ "id": "…", "name": "default", "prefix": "grag_QcmU3L6",
   "expires_at": null, "revoked_at": null, "last_used_at": "…", "created_at": "…" }]

Revoke a key

DELETE /v1/keys/{id} → 204

Revocation is a soft-delete (sets revoked_at), so the audit trail survives. Revoking an already-revoked key is a safe no-op.

← PreviousAuthentication Next →Documents & Jobs