Agentic Integration

Atiru provides reference endpoints that AI agents can use to discover the API, learn allowed operations, and integrate without prior configuration.

Reference endpoints (no auth)

These endpoints do not require authentication:

Endpoint	Description
GET /reference/for-agents	Discovery payload: base URL, auth, operations, content types, error codes
GET /reference/allowed-content-types	List of allowed MIME types for uploads
GET /reference/openapi.json	OpenAPI 3.0 specification

Agent discovery: GET /reference/for-agents

Returns everything an agent needs to integrate:

• base_url — API base URL (e.g. https://api.atiru.io)
• auth — How to authenticate (Authorization: Bearer <key> or X-Api-Key)
• operations — List of endpoints with method, path, auth required, rate limits
• allowed_content_types — MIME types accepted for upload
• error_codes — Machine-readable error codes and descriptions

curl

curl "https://api.atiru.io/reference/for-agents"

Response (200)

{
  "base_url": "https://api.atiru.io",
  "auth": {
    "type": "Bearer",
    "header": "Authorization",
    "description": "Use Authorization: Bearer <your_api_key>",
    "x_api_key_note": "X-Api-Key header is also accepted."
  },
  "operations": [
    {
      "method": "POST",
      "path": "/files",
      "summary": "Upload a file",
      "requires_auth": true,
      "request_headers": "Content-Type, optional x-file-name",
      "request_body_notes": "Binary body",
      "response_notes": "201 with file object",
      "rate_limit_per_min": 30
    }
  ],
  "allowed_content_types": ["image/jpeg", "image/png", "..."],
  "error_codes": [
    {
      "code": "MISSING_AUTH",
      "http_status": 401,
      "description": "Missing or invalid Authorization header"
    }
  ]
}

Allowed content types: GET /reference/allowed-content-types

Returns an array of MIME type strings accepted for POST /files.

curl

curl "https://api.atiru.io/reference/allowed-content-types"

Response (200)

["image/jpeg", "image/png", "image/gif", "application/pdf", "..."]

OpenAPI spec: GET /reference/openapi.json

Returns the full OpenAPI 3.0 specification for the API. Use it with code generators or API clients.

curl

curl "https://api.atiru.io/reference/openapi.json" -o openapi.json

Using an LLM to consume the API

You can point an LLM at the reference endpoint and ask it to build something that uses the API. The LLM will read the discovery payload (and optionally the OpenAPI spec) and generate code or behavior.

Example prompt

Give your LLM a prompt like:

Use the API documentation at https://api.atiru.io/reference/for-agents. Fetch that URL to get the base URL, auth details, and list of operations. Then build me a simple filesystem client that can list my files, upload a file, and delete a file. Use the API key I provide; assume it is in an environment variable ATIRU_API_KEY.

The LLM can also be given https://api.atiru.io/reference/openapi.json for full request/response shapes.

How the LLM consumes the endpoints

1. GET /reference/for-agents (no auth) — The LLM fetches this first. The response contains base_url, auth (e.g. Authorization: Bearer <key>), operations (method, path, summary per endpoint), allowed_content_types, and error_codes. From this, the LLM knows where to send requests and how to authenticate.
2. GET /reference/openapi.json (optional) — For precise request bodies and response schemas, the LLM can fetch the OpenAPI spec and use it to generate correct code (e.g. headers, query params, body shape).
3. Authenticated calls — Using base_url and the auth description, the LLM then calls endpoints such as GET /files, POST /files, DELETE /files/:id with the user's API key.

No prior API documentation needs to be pasted into the chat; the reference endpoints are self-describing so the LLM can discover and use the API at runtime.

Error handling

When an API call fails, the response body includes error (message) and optionally code (machine-readable). Match code against error_codes from GET /reference/for-agents for programmatic handling.

Common codes: MISSING_AUTH, INVALID_OR_EXPIRED_TOKEN, RATE_LIMITED, FILE_TOO_LARGE, FILE_NOT_FOUND.