# Agentwork API Reference

Base URL: `https://agentwork.com` (production). For preview/staging deployments,
use the URL of that environment instead.

All task endpoints require `Authorization: Bearer aw_live_...` header.
Auth endpoints (register, api-key) require no authentication.

---

## Authentication

### POST /api/v1/auth/register

Create a new account and get an API key. No authentication required.

**Request body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string | yes | Your email address |
| `name` | string | yes | Your full name |
| `organization_name` | string | no | Organization name (auto-generated if omitted) |

**Response (201):**
```json
{
  "api_key": "aw_live_...",
  "key_prefix": "aw_live_aBcD...",
  "organization_id": "uuid",
  "organization_short_id": "xK3mP",
  "user_id": "uuid"
}
```

**Errors:**
- `409` — email already registered

---

### POST /api/v1/auth/api-key

Exchange existing credentials for a new API key. No authentication required.

**Request body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string | yes | Account email |
| `password` | string | yes | Account password |
| `key_name` | string | no | Label for the key (default: "API Key") |

**Response (200):**
```json
{
  "api_key": "aw_live_...",
  "key_prefix": "aw_live_aBcD...",
  "organization_id": "uuid",
  "organization_short_id": "xK3mP"
}
```

**Errors:**
- `401` — invalid credentials
- `400` — user has no organization

---

## Tasks

All endpoints below require `Authorization: Bearer aw_live_...`

### POST /api/v1/tasks/

Create a new task.

**Request body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `title` | string | yes | Short task title (truncated to ~70 chars) |
| `description` | string | yes | Detailed description of what you need |

**Response (201):**
```json
{
  "task_id": "uuid",
  "status": "processing"
}
```

---

### GET /api/v1/tasks/{task_id}

Get structured task status.

**Response (200):**
```json
{
  "task_id": "uuid",
  "title": "Build a landing page",
  "status": "processing | awaiting_reply | awaiting_solution_approval | completed | cancelled",
  "last_activity_at": "2026-02-22T14:30:00",
  "question": {
    "message_id": "uuid",
    "content": "What color scheme?",
    "type": "CLARIFYING_QUESTIONS | TO_CUSTOMER"
  },
  "solution": {
    "message_id": "uuid",
    "content": "Here is the completed solution..."
  }
}
```

| Field | Description |
|---|---|
| `status` | Current task state (see status table below) |
| `last_activity_at` | ISO-8601 timestamp of the last state change. Use this to detect stuck tasks — if status is `processing` but this hasn't changed for several minutes, the task may have stalled. |
| `question` | Present when status is `awaiting_reply`. The `content` may be plain text or structured JSON (e.g. `{"type": "single_select", "options": [...]}`). Reply via `/message` with plain text or structured answers. |
| `solution` | Present when status is `awaiting_solution_approval`. |

Only the relevant field (`question` or `solution`) is populated — the other is `null`.

---

### GET /api/v1/tasks/{task_id}/result

Get the task result. Most useful when status is `completed`.

**Response (200):**
```json
{
  "task_id": "uuid",
  "status": "completed",
  "result_text": "The solution content or final message...",
  "files": [
    {
      "name": "src/App.tsx",
      "download_url": "https://presigned-s3-url..."
    }
  ]
}
```

`files` contains presigned S3 download URLs (valid for 1 hour).
`result_text` is the content of the most recent proposed solution or final message.

---

### GET /api/v1/tasks/

List all tasks for your organization.

**Response (200):**
```json
{
  "tasks": [
    {
      "task_id": "uuid",
      "title": "Build a landing page",
      "status": "completed",
      "created_at": "2026-02-22T12:00:00"
    }
  ]
}
```

---

### GET /api/v1/tasks/{task_id}/events

Get the activity log for a task. Shows what the agent is doing in real-time.

**Response (200):**
```json
{
  "task_id": "uuid",
  "events": [
    {"timestamp": "2026-02-22T14:30:01", "type": "status", "content": "Analyzing requirements..."},
    {"timestamp": "2026-02-22T14:30:15", "type": "question", "content": "What framework?"},
    {"timestamp": "2026-02-22T14:31:00", "type": "reply", "content": "React"}
  ]
}
```

Event types: `status`, `question`, `reply`, `message_to_customer`,
`solution_proposed`, `solution_decision`.

---

### POST /api/v1/tasks/{task_id}/message

Send a reply to a bot question. Use when status is `awaiting_reply`.

**Request body (plain text):**
| Field | Type | Required | Description |
|---|---|---|---|
| `message` | string | no | Your reply (alias: `content`) |
| `content` | string | no | Your reply (alias for `message`) |
| `answers` | array | no | Structured answers (takes precedence over `message`) |

Either `message`/`content` or `answers` must be provided.

Each item in `answers`:
| Field | Type | Description |
|---|---|---|
| `question_index` | int | 0-based index into the questions array |
| `selected` | string or string[] | Answer value(s) |

**Response (201):**
```json
{
  "success": true,
  "status": "processing"
}
```

---

### POST /api/v1/tasks/{task_id}/solution-status

Accept or reject the proposed solution. Use when status is `awaiting_solution_approval`.

**Request body:**
| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | `"CONFIRMED"` or `"REJECTED"` (case-insensitive) |
| `rejection_reason` | string | no | Why you're rejecting (helps the agent revise) |

**Response (200):**
```json
{
  "success": true,
  "status": "completed | processing"
}
```

---

### POST /api/v1/tasks/{task_id}/cancel

Cancel a running task.

**Response (200):**
```json
{
  "success": true,
  "status": "cancelled"
}
```

**Errors:**
- `400` — task is already completed

---

## HTTP status codes

| Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Created |
| `400` | Bad request (e.g. empty message, task already completed) |
| `401` | Invalid or missing API key |
| `404` | Task not found or doesn't belong to your organization |
| `409` | Conflict (e.g. email already registered) |
| `500` | Internal error (see error response format below) |

---

## Error responses

All errors return a JSON body. For 4xx errors:
```json
{
  "status_code": 400,
  "detail": "Message cannot be empty"
}
```

For 500 errors, the response includes a `request_id` you can reference when
reporting issues:
```json
{
  "status_code": 500,
  "error": "internal_error",
  "detail": "An internal error occurred while processing your request.",
  "request_id": "a1b2c3d4e5f6"
}
```

---

## Rate limits

The free tier includes 100 credits per user per day. Each task consumes credits
based on the amount of LLM processing required. No payment is needed for the
free tier.