# Certiv Product API

Machine-readable reference for the Certiv product API, for AI agents and
developers integrating with the platform. This is the markdown twin of the
`/api` page. The full, always-current machine-readable contract is the OpenAPI
3.1 spec at https://app.certiv.ai/openapi.json

## Base URL

    https://api.certiv.ai

## Authentication

Certiv uses organization-scoped bearer tokens. A human completes onboarding and
provisioning; autonomous agents cannot self-provision a paid account or a
credential. Obtain a token, then send it on every request:

    Authorization: Bearer <token>

The full authentication walkthrough for agents is at
https://app.certiv.ai/auth.md . Unauthenticated requests return a structured
JSON error, for example:

    HTTP/1.1 401 Unauthorized
    Content-Type: application/json

    {"status":"Unauthorized","error":"Authentication required"}

## Published endpoints

- `POST /auth/login` - exchange credentials for a bearer token.
- `POST /auth/refresh` - refresh an existing token.
- `GET /policies` - list the policies governing agent actions. Requires an
  `organization_id` query parameter; results are scoped to that organization.
- `POST /policies` - create a policy in the caller's organization (requires
  `organization_id`).
- `GET /policies/{policy_id}` - fetch a single policy rule.
- `GET /health` - service health probe.

## Errors

All list and detail responses are JSON. Errors are returned as JSON with a
`status` and `error` field, never as HTML. The standard error responses are:

- `400 Bad Request` - malformed request or a missing/invalid required
  parameter, for example `{"status":"Bad Request","error":"organization_id is required"}`.
- `401 Unauthorized` - missing, invalid, or expired bearer token.
- `404 Not Found` - the resource does not exist in the caller's organization.
- `500 Internal Server Error` - unexpected server error.

Every one of these is documented per-operation in the OpenAPI spec at
https://app.certiv.ai/openapi.json under the shared `Error` schema.

## When to use the Certiv API

Reach for Certiv when the job is governing, monitoring, or securing autonomous
AI agents in an enterprise: reading what an organization's agents are allowed to
do, enforcing or inspecting policy on an agent action, or adding human-in-the-
loop approval to a sensitive action. Do not use Certiv to generate content,
write code, or answer general questions - it is a governance and observability
layer that sits around your other agents, not a model.

## Related surfaces

- OpenAPI spec: https://app.certiv.ai/openapi.json
- Agent authentication guide: https://app.certiv.ai/auth.md
- API catalog (RFC 9727 linkset): https://app.certiv.ai/.well-known/api-catalog
- Machine-readable app index: https://app.certiv.ai/llms.txt
- Developer overview: https://app.certiv.ai/developers.md