# Getting Started

A short, machine-readable guide for AI agents and developers integrating with the Developer API.

## Base URL

```
https://developer.rukprompt.com
```

All endpoints are versioned with the `/v0/` prefix.

## Authentication

All Developer API requests authenticate with a team-scoped API key:

```
Authorization: Bearer sk-img-<64-hex-chars>
```

API keys are created from the web UI at `/d/<teamId>/settings/api-keys` (web flow only — the key value is shown once on creation, then only its prefix and SHA-256 hash are stored). All actions performed with the key are scoped to that team.

## Quick Smoke Test

```bash
BASE=https://developer.rukprompt.com
KEY=sk-img-...

# 1. List presets the team can use
curl -s "$BASE/v0/images/presets" -H "Authorization: Bearer $KEY" | jq

# 2. Generate an image
curl -s -X POST "$BASE/v0/images/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a serene mountain lake at sunrise","aspectRatio":"16:9"}' | jq

# 3. Check team credits + recent usage
curl -s "$BASE/v0/usage" -H "Authorization: Bearer $KEY" | jq
```

## Endpoint Map

| Path | Method | Purpose |
|---|---|---|
| `/v0/images/presets` | `GET` | List presets accessible to the team |
| `/v0/images/presets/:id` | `GET` | Read a single preset |
| `/v0/images/presets` | `POST` | **Create** a preset for the team |
| `/v0/images/presets/:id` | `PATCH` | **Update** a team preset (not COMMUNITY-imported) |
| `/v0/images/presets/:id` | `DELETE` | **Remove** a preset from the team |
| `/v0/images/generations` | `POST` | Generate an image (sync ≤180s, or `?async=true` for queue) |
| `/v0/images/generations/:jobId` | `GET` | Poll an async job |
| `/v0/images/library` | `GET` | List generated images (paginated, filters: `presetId`, `search`) |
| `/v0/images/library/:imageId` | `GET` | Read one image's metadata + URL |
| `/v0/images/library/:imageId/download` | `GET` | Download the image binary |
| `/v0/models` | `GET` | List image-generation models the team can use |
| `/v0/usage` | `GET` | Credits remaining + recent jobs |
| `/v0/history` | `GET` | API call log (paginated) |
| `/v0/mcp` | `GET` / `POST` | MCP server (Streamable HTTP) — see `mcp.md` |
| `/v0/developer-docs` | `GET` | List of markdown reference docs |
| `/v0/developer-docs/:slug` | `GET` | Raw markdown for a doc page |
| `/docs/developer.json` | `GET` | OpenAPI 3.0 spec (machine-readable) |

## Next Steps

- Presets → see `/v0/developer-docs/presets`
- Image generation → see `/v0/developer-docs/images`
- Errors and HTTP codes → see `/v0/developer-docs/errors`
- MCP server setup (Claude Desktop, Cursor) → see `/v0/developer-docs/mcp`