Documentation

API Reference

Janus exposes HTTP REST and gRPC APIs. All SDKs communicate through these endpoints.

Base URL

http://localhost:8080

All requests require the X-Tenant-ID header. Authenticated endpoints require an Authorization: Bearer <api_key> header.

REST Endpoints

Health & Readiness

GET/healthz

Liveness probe. Returns 200 when the process is alive.

GET/readyz

Readiness probe. Checks PG, NATS, Redis connectivity. Returns 200 only when all dependencies are reachable.

Mailboxes

POST/api/v1/mailboxes

Create a mailbox. Body: { "name": "review-mb", "agent_id": "reviewer" }

GET/api/v1/mailboxes/{name}

Get mailbox details and stats.

GET/api/v1/mailboxes

List all mailboxes for the tenant.

DELETE/api/v1/mailboxes/{name}

Delete a mailbox (must be empty).

Tasks

POST/api/v1/tasks

Publish a task. Body: { "id", "source_agent", "target_type", "target_value", "envelope" }

POST/api/v1/mailboxes/{name}/pull

Pull next pending task from a mailbox. Body: { "agent_id": "reviewer" }

POST/api/v1/tasks/{id}/start

Start task processing. Body: { "lease_id": "..." }

POST/api/v1/tasks/{id}/ack

Acknowledge successful completion. Body: { "lease_id": "...", "result_ref": "..." }

POST/api/v1/tasks/{id}/nack

Negative ACK — return to queue or DLQ. Body: { "lease_id": "...", "reason": "..." }

GET/api/v1/tasks/{id}

Get task details and current state.

GET/api/v1/tasks

List tasks with optional filters (status, mailbox, source).

POST/api/v1/tasks/{id}/replay

Replay a task from DLQ back to pending.

Intent Resolution

POST/api/v1/intent/resolve

Resolve natural language to capability. Body: { "query": "Review Go code for bugs", "tenant_id": "acme" }

Artifacts

POST/api/v1/artifacts

Upload an artifact. Multipart form with tenant isolation.

GET/api/v1/artifacts/{id}

Download an artifact (tenant-scoped access check).

Error Format

All errors return a standard envelope:

{
    "error": {
        "code": "TENANT_MISMATCH",
        "message": "Cross-tenant access denied",
        "details": {
            "request_tenant": "acme",
            "resource_tenant": "evil-corp"
        }
    }
}

HTTP Status	Error Code	Description
400	INVALID_REQUEST	Malformed request body
401	UNAUTHENTICATED	Missing or invalid API key
403	TENANT_MISMATCH	Cross-tenant access denied
403	POLICY_DENIED	Governance policy blocked the operation
404	NOT_FOUND	Resource not found
409	LEASE_EXPIRED	Task lease expired, re-pull required
429	RATE_LIMITED	Budget or concurrency limit exceeded
500	INTERNAL	Server error

Authentication

Janus supports two authentication modes:

API Key (default, enabled) — pass key via Authorization: Bearer <key> header
mTLS — mutual TLS with client certificates

API keys are tenant-scoped. Create and revoke keys via the CLI:

janus auth create-key --tenant acme --role admin
janus auth revoke-key --tenant acme --key-id <id>

The full protobuf service definitions and gRPC reflection are available on the server. See the GitHub repo for proto files.