---
slug: developer-api-quickstart
title: Quickstart: create your first Task
category: capability
status: published
tags: [api, quickstart, create task, backend, curl, getting started, 快速开始, 创建任务, 后端]
aliases: []
lastEditAt: 2026-08-02
---
Five minutes from nothing to a finished result.

### 1. Mint a key

An owner or admin creates one workspace-scoped key through the
session-authenticated developer endpoint (see *Authentication and billing*).
The raw `tyc_...` token is shown once — store it as a secret.

### 2. Create one Task

Every create needs an `Idempotency-Key` header so a retry cannot produce a
second Task:

```bash
curl -sS https://tycoon.us/api/public/tasks \
  -H "Authorization: Bearer $TYCOON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: competitor-research-2026-08-01" \
  -d '{"prompt":"Research the three closest competitors and summarize their pricing."}'
```

Because this request omits `workspace_id`, Tycoon creates an isolated
task-bound workspace for the Task. The API key's controller workspace remains
the billing account.

### 3. Keep the id

The response returns immediately, before any work runs:

```json
{
  "task": {
    "id": "cm...",
    "title": "Competitor research",
    "status": "queued",
    "created_at": "2026-08-01T12:00:00.000Z"
  },
  "idempotent_replay": false
}
```

### 4. Read it until it is usable

Poll the Task, honoring `poll_after_ms` between reads:

```bash
curl -sS https://tycoon.us/api/public/tasks/cm... \
  -H "Authorization: Bearer $TYCOON_API_KEY"
```

The read returns `status`, and once the work is done, `result.text` plus the
actual `usage` that was metered. Statuses are `queued`, `running`,
`requires_action`, `waiting`, `completed`, or `canceled`.

### 5. Handle the two things that interrupt it

If `status` is `requires_action`, read `required_actions` and resolve the
decision from your backend when `api_resolvable` is `true` (see *Resolve a
required action from your backend*). If you would rather be told than poll,
register a webhook receiver (see *Check-in and terminal webhooks*).

No SDK, browser session, or knowledge of Tycoon's internal agents is required.

## Next steps

- [Authentication and workspace billing](/help/developer-api-authentication-billing)
- [Publish a workspace method as an API](/help/developer-api-published-method)
- [Create and read Tasks](/help/developer-api-create-read-tasks)
- [Webhooks](/help/developer-api-webhooks)