# HIIE v1 API

> Headless, agent-facing access to the HIIE workflow engine — projects, builds, CAD, flows, and artifacts.

The v1 API is the same engine the HIIE app drives, behind a Bearer API key. Every
endpoint is **owner-scoped** to the key's tenant.

- **Base URL:** `https://hiie.arthurlabs.net/api/v1`
- **OpenAPI:** [https://hiie.arthurlabs.net/.well-known/openapi.json](https://hiie.arthurlabs.net/.well-known/openapi.json)
- **API catalog:** [https://hiie.arthurlabs.net/.well-known/api-catalog](https://hiie.arthurlabs.net/.well-known/api-catalog)
- **Auth model:** [https://hiie.arthurlabs.net/auth.md](https://hiie.arthurlabs.net/auth.md)
- **MCP server:** `https://hiie.arthurlabs.net/api/mcp` (Streamable HTTP) — see the [server card](https://hiie.arthurlabs.net/.well-known/mcp/server-card.json)
- **Health:** [https://hiie.arthurlabs.net/api/health](https://hiie.arthurlabs.net/api/health)

## Authentication

Mint a key at https://hiie.arthurlabs.net/account and send it on every request:

```
Authorization: Bearer hk_live_<id>.<secret>
```

Keys carry scopes — `read`, `write`, `build` (`admin` implies all). Each
operation below lists the scope it needs. A missing/invalid key returns `401`
with a `WWW-Authenticate` header pointing at the
[protected-resource metadata](https://hiie.arthurlabs.net/.well-known/oauth-protected-resource); an
under-scoped key returns `403`.

## Endpoints

| Method | Path | Scope | Purpose |
| --- | --- | --- | --- |
| GET | `/projects` | read | List the tenant's projects |
| POST | `/projects` | write | Create a project |
| GET | `/projects/{id}/build` | read | Poll a build job (reports `stalled`) |
| POST | `/projects/{id}/build` | build | Start or resume the autonomous builder |
| GET | `/projects/{id}/cad` | read | List archived CAD designs |
| POST | `/projects/{id}/cad` | build | Generate a manufacturable part |
| GET | `/projects/{id}/flows/run` | read | Discover flow templates |
| POST | `/projects/{id}/flows/run` | build | Run a flow template or custom flow |
| GET | `/projects/{id}/artifacts` | read | Manifest of every file (with download URLs) |
| POST | `/projects/{id}/artifacts` | write | Bulk-write files into a project |
| GET | `/projects/{id}/artifacts/{folder}/{name}` | read | Download one file with the right Content-Type |

## Quick start

```bash
# 1. Create a project
curl -X POST "https://hiie.arthurlabs.net/api/v1/projects" \
  -H "Authorization: Bearer $HIIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Desk lamp","kind":"hardware"}'
# → 201 { "id": "...", "name": "Desk lamp", ... }

# 2. Generate a part
curl -X POST "https://hiie.arthurlabs.net/api/v1/projects/$PROJECT_ID/cad" \
  -H "Authorization: Bearer $HIIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"M3 cable clip, 20mm wide"}'

# 3. List what the project holds
curl "https://hiie.arthurlabs.net/api/v1/projects/$PROJECT_ID/artifacts" \
  -H "Authorization: Bearer $HIIE_API_KEY"
```

## Error model

Errors are JSON `{ "error": "<reason>" }` with a standard status code: `400`
(bad request), `401` (no/invalid key), `403` (missing scope), `404` (no such
project), `422` (engine could not produce output), `503` (service
unavailable). Long-running operations (build, CAD, flows) are capped at 300s per
invocation; the build endpoint is resumable via `POST {resume:true}`.

## Skills

Machine-readable capability docs are published at
[https://hiie.arthurlabs.net/.well-known/agent-skills/index.json](https://hiie.arthurlabs.net/.well-known/agent-skills/index.json).

## Contact

support@arthurlabs.net · HIIE is built by Arthur Labs, Inc.