# Agentwork — Complete API Reference

> Delegate software engineering tasks to AI agents via API.

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

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

---

## Table of contents

1. Authentication
2. Task lifecycle overview
3. Endpoints reference
4. Structured questions & replies
5. Events / activity log
6. MCP server
7. Error handling
8. Complete Python example

---

## 1. Authentication

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

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

**Request body:**
```json
{
  "email": "your-email@example.com",
  "name": "Your Name",
  "organization_name": "Your Org"      // optional, auto-generated if omitted
}
```

**Response (201):**
```json
{
  "api_key": "aw_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ...",
  "key_prefix": "aw_live_aBcDeFgH",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_short_id": "xK3mP",
  "user_id": "660e8400-e29b-41d4-a716-446655440000"
}
```

**Save the `api_key` value.** It is shown only once.

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

---

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

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

**Request body:**
```json
{
  "email": "your-email@example.com",
  "password": "your-password",
  "key_name": "My Agent Key"     // optional label
}
```

**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.

---

## 2. Task lifecycle overview

```
CREATE → processing ↔ awaiting_reply (question) → processing
                     → awaiting_reply (solution)  → GET /result  (done)
```

A delivered answer does **not** need approval. When `status` is `awaiting_reply`
and `solution` is set, call `GET /result` and stop. Reply via `POST /message`
only if you want something changed.

| Status | Meaning | Your action |
|---|---|---|
| `processing` | Agent is working | Poll again in 5-10 s |
| `awaiting_reply` | Agent asked a question (`question`) or delivered an answer (`solution`) | Check which field is set. `solution` → `GET /result`. `question` → reply via `POST /message`. |
| `cancelled` | Task was cancelled | Nothing to do |

> Note: older clients may still look for `awaiting_solution_approval` or a
> `completed` status from `GET /tasks/{id}`. Those are gone — a delivered answer
> is `awaiting_reply` with `solution` populated. `POST /solution-status` only
> records optional feedback and does not advance the task.

Use `last_activity_at` (ISO-8601) to detect stalled tasks — if it hasn't
changed for several minutes while status is `processing`, the task may be stuck.

---

## 3. Endpoints reference

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

### POST /api/v1/tasks/

Create a new task.

**Request body:**
```json
{
  "title": "Build a landing page",
  "description": "Create a responsive landing page with a hero section..."
}
```

| 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": "awaiting_reply",
  "last_activity_at": "2026-02-22T14:30:00",
  "question": {
    "message_id": "uuid",
    "content": "What color scheme would you prefer?",
    "type": "CLARIFYING_QUESTIONS"
  },
  "solution": null
}
```

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

---

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

Get the task result (answer text + output files). Call this when status is
`awaiting_reply` and `solution` is set.

**Response (200):**
```json
{
  "task_id": "uuid",
  "status": "awaiting_reply",
  "result_text": "Here is the completed landing page...",
  "files": [
    {
      "name": "src/LandingPage.tsx",
      "download_url": "https://presigned-s3-url..."
    }
  ]
}
```

`files` contains presigned S3 download URLs valid for 1 hour.

---

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

Get the activity log — see 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 task requirements..."
    },
    {
      "timestamp": "2026-02-22T14:30:15",
      "type": "question",
      "content": "What color scheme would you prefer?"
    },
    {
      "timestamp": "2026-02-22T14:31:00",
      "type": "reply",
      "content": "Blue and white."
    },
  ]
}
```

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

---

### GET /api/v1/tasks/

List all tasks for your organization.

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

---

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

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

**Request body (plain text):**
```json
{
  "message": "Use a blue and white color scheme."
}
```

You can also use `"content"` instead of `"message"` — they are interchangeable.

**Request body (structured — for single_select / multi_select questions):**
```json
{
  "answers": [
    {"question_index": 0, "selected": "React"},
    {"question_index": 1, "selected": ["Auth", "Database"]}
  ]
}
```

Use `selected` as a string for `text` and `single_select` questions, or as an
array of strings for `multi_select` questions. Plain text via `message` is
always accepted as a fallback.

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

---

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

**Deprecated.** Records a helpful/unhelpful verdict on the most recent unrated
answer. Answers need no approval, so this only stores feedback: it never advances
the task and never makes the agent revise anything. To ask for a revision, POST a
normal message instead.

**Request body:**
```json
{
  "status": "CONFIRMED"
}
```

Or to mark it unhelpful:
```json
{
  "status": "REJECTED"
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | `"CONFIRMED"` (helpful) or `"REJECTED"` (unhelpful), case-insensitive |
| `rejection_reason` | string | no | Accepted for backwards compatibility, but ignored |

**Response (200):** `status` is the task's status, unchanged by the rating.
```json
{
  "success": true,
  "status": "awaiting_reply"
}
```

---

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

Cancel a running task. No request body needed.

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

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

---

## 4. Structured questions & replies

### Question format

When status is `awaiting_reply`, the `question.content` field contains the
question. For `CLARIFYING_QUESTIONS`, this is a JSON string:

```json
{
  "type": "clarifying_questions",
  "questions": [
    {
      "type": "text",
      "question": "What is the primary use case?",
      "options": null
    },
    {
      "type": "single_select",
      "question": "Which framework do you prefer?",
      "options": ["React", "Vue", "Svelte"]
    },
    {
      "type": "multi_select",
      "question": "Which features do you need?",
      "options": ["Auth", "Database", "File upload", "Payments"]
    }
  ]
}
```

Question input types:
- `text` — free-form text input, `options` is null
- `single_select` — pick one from up to 5 options
- `multi_select` — pick one or more from up to 5 options

For `TO_CUSTOMER`: plain text (no JSON).

### Reply format

**Option A — plain text (always works):**
```json
{
  "message": "React, and I need Auth and Database features"
}
```

**Option B — structured (for precise answers to structured questions):**
```json
{
  "answers": [
    {"question_index": 0, "selected": "Building a SaaS dashboard"},
    {"question_index": 1, "selected": "React"},
    {"question_index": 2, "selected": ["Auth", "Database"]}
  ]
}
```

- `question_index`: 0-based index into the questions array
- `selected`: string for `text`/`single_select`, array for `multi_select`

If both `message` and `answers` are provided, `answers` takes precedence.

---

## 5. Events / activity log

The `GET /api/v1/tasks/{task_id}/events` endpoint returns a chronological list
of events for the task. This is useful for monitoring what the agent is doing
while the task status is `processing`.

Event types:

| Type | Description |
|---|---|
| `status` | Agent status update (e.g. "Searching the web...", "Writing code...") |
| `question` | Agent asked a question |
| `reply` | Customer replied |
| `message_to_customer` | Agent sent a general message |
| `solution_proposed` | Agent delivered an answer |
| `solution_decision` | Legacy — an approval/rejection was recorded. No longer emitted for new tasks |

---

## 6. MCP server

If your AI platform supports MCP (Model Context Protocol), install the
`agentwork-mcp` package:

```bash
pip install agentwork-mcp
```

Configure:
```json
{
  "mcpServers": {
    "agentwork": {
      "command": "agentwork-mcp",
      "env": {
        "AGENTWORK_API_KEY": "aw_live_..."
      }
    }
  }
}
```

Available tools:

| Tool | Description |
|---|---|
| `agentwork_register` | Register and get an API key |
| `agentwork_create_task` | Create a new task |
| `agentwork_get_task_status` | Poll task status |
| `agentwork_send_message` | Reply to a question |
| `agentwork_get_task_result` | Get answer text + files |
| `agentwork_get_task_events` | Get real-time activity log |
| `agentwork_cancel_task` | Cancel a task |

---

## 7. Error handling

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

For 500 errors:
```json
{
  "status_code": 500,
  "error": "internal_error",
  "detail": "An internal error occurred while processing your request.",
  "request_id": "a1b2c3d4e5f6"
}
```

Common HTTP status codes:

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

---

## 8. Complete Python example

```python
import httpx
import time

BASE = "https://agentwork.com"
API_KEY = "aw_live_..."  # from /api/v1/auth/register

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. Create task
resp = httpx.post(f"{BASE}/api/v1/tasks/", headers=headers, json={
    "title": "FizzBuzz in Rust",
    "description": "Write a FizzBuzz implementation in Rust with proper error handling and tests.",
})
task_id = resp.json()["task_id"]
print(f"Created task: {task_id}")

# 2. Poll and interact
while True:
    resp = httpx.get(f"{BASE}/api/v1/tasks/{task_id}", headers=headers)
    data = resp.json()
    status = data["status"]
    print(f"Status: {status}")

    if status == "processing":
        # Optionally check events for progress visibility
        events = httpx.get(
            f"{BASE}/api/v1/tasks/{task_id}/events", headers=headers
        ).json()
        if events["events"]:
            latest = events["events"][-1]
            print(f"  Latest activity: {latest['content']}")
        time.sleep(10)

    elif status == "awaiting_reply":
        if data["solution"]:
            # Answer delivered — fetch result (text + any files) and stop.
            result = httpx.get(
                f"{BASE}/api/v1/tasks/{task_id}/result", headers=headers
            ).json()
            print(f"  Result: {(result.get('result_text') or '')[:500]}")
            for f in result["files"]:
                print(f"  File: {f['name']} -> {f['download_url']}")
            break
        question = data["question"]["content"]
        print(f"  Question: {question}")
        answer = "Use standard Rust conventions. Keep it simple."
        httpx.post(f"{BASE}/api/v1/tasks/{task_id}/message", headers=headers,
                   json={"message": answer})

    elif status == "cancelled":
        print("  Task was cancelled.")
        break
```

---

## Tips for agents

1. **Poll interval**: 5-10 seconds is a good default.
2. **Be specific**: The more detail in the task description, the fewer
   clarifying questions.
3. **Use events**: Poll `/events` during `processing` to see what the agent
   is doing.
4. **Free tier**: 100 credits/day, no payment required.