# Kamai Takeoff API quickstart

Kamai (kamai.io) turns construction PDF sheet sets into GeoJSON quantities.
This page is the markdown contract companion. The live spec is
https://api.kamai.io/openapi.json. Ship clients from that document.

Keys: https://admin.kamai.io
Human hub: https://kamai.io/developers/api
MCP (OAuth, not API-key): https://mcp.kamai.io/mcp

## Authenticate

The API uses a static API-key bearer token. Get a key from the Kamai Console at
https://admin.kamai.io (sign in, create an API key). Send it on every request:

```
Authorization: Bearer <YOUR_API_KEY>
```

## 1. Upload a PDF sheet set

```
POST https://api.kamai.io/v1/blueprints/upload
Authorization: Bearer <YOUR_API_KEY>
Content-Type: multipart/form-data

file=@drawing.pdf
```

Optional query param `project_id`. When omitted, your Default Project is used
or created. The JSON body is `{ "job_id": "<uuid>", "project_id": "<id>" }`.
There is no `blueprint_id` on this response.

Input is a PDF. There is no official SDK; any HTTP client works.

## 2. Poll the project for the job

```
GET https://api.kamai.io/v1/projects/{project_id}
Authorization: Bearer <YOUR_API_KEY>
```

The body is `{ "project": { "jobs": { "<job_id>": { ... } } } }`. `jobs` is a
map keyed by job id, not an array. Read `project.jobs[job_id]`.

Each job has `id`, `status`, `blueprint_id`, and `filename`. Repeat until
`status` is not `PENDING` or `RUNNING`. Then read `blueprint_id` from that
job. Webhooks are coming soon; poll for now.

## 3. Fetch the GeoJSON result

```
GET https://api.kamai.io/v1/blueprints/{blueprint_id}
Authorization: Bearer <YOUR_API_KEY>
```

The body is `{ "blueprint": { "geojson": { ... }, ... } }`. Persist `job_id`,
`project_id`, and `blueprint_id` yourself.

## What this API is not

Kamai is an ingestion takeoff API, not a generic datastore. There is no search
or query endpoint over quantities. You cannot list blueprints except by id
after a job succeeds. `GET /v1/projects` lists projects, not takeoff results.

This is Kamai (kamai.io): construction takeoff AI. It is not Kimai (time
tracking), not KamAI EMR, and not a media player. Blog posts on kamai.io that
rank for "API docs" are explainers, not the spec.

## Reference

- OpenAPI spec: https://api.kamai.io/openapi.json
- Swagger UI: https://api.kamai.io/docs (explorer; the contract is OpenAPI)
- Agent skill: https://kamai.io/.well-known/agent-skills/kamai-takeoff-api/SKILL.md
- llms.txt: https://kamai.io/llms.txt