## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://developer.audioshake.ai/llms.txt)

Use this file to discover all available pages before exploring further.

AudioShake sends a `POST` request to your webhook URL each time a [Task’s](https://developer.audioshake.ai/api-reference/tasks/create) Target changes status. The payload is the full Task object, identical to the response from [Get Task by ID](https://developer.audioshake.ai/api-reference/tasks/get).

## Setup

You can configure a webhook URL in two ways:

- **Globally** — set a default webhook URL in the [AudioShake Dashboard](https://dashboard.audioshake.ai/) under **Settings > Webhook URL**. It applies to every Task on your account.
- **Per Task** — set `webhookUrl` in the body of your [Create Task](https://developer.audioshake.ai/api-reference/tasks/create) request. This applies to that Task only.

A `webhookUrl` set on a Task overrides the global webhook URL configured in the dashboard for that Task. If no `webhookUrl` is provided on the Task, the global dashboard URL is used.

### Per-Task webhook example

```bash
curl --location 'https://api.audioshake.ai/tasks' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
    "url": "https://demos.audioshake.ai/demo-assets/shakeitup.mp3",
    "webhookUrl": "https://your-server.com/webhooks/audioshake",
    "targets": [
        {
            "model": "vocals",
            "formats": ["mp3"]
        },
        {
            "model": "instrumental",
            "formats": ["mp3"]
        }
    ]
}'
```

## When webhooks fire

A webhook is sent each time a Target completes or errors. There is no callback when a Target is first created or begins processing — the first webhook you receive for a given Target will be `completed` or `error`.

Webhooks fire per Target, not once per Task. If a Task has three targets, you will receive up to three webhook requests.

## Target status reference

| Status      | Meaning                                 | What to do                                                        |
|-------------|-----------------------------------------|------------------------------------------------------------------|
| `processing`| Target is actively being processed      | No webhook is sent for this state — wait for `completed` or `error`|
| `completed` | Results are ready                       | Download files from the `output[].link` fields                   |
| `error`     | Processing failed                       | Check the `error` field for details                               |

Note: other targets in the same Task may still show `processing` when the webhook fires — this is expected.

## Payload

The payload contains the full Task object. Each target includes its current status — some may be `completed` while others are still `processing`:

```json
{
  "id": "cmn5h1wv600edx8fgoboeeg06",
  "createdAt": "2026-03-25T03:16:17.442Z",
  "clientId": "cm4lousna0yurbk8ngu31n8bb",
  "assetId": "cmn5gz2s800xp01phe9v3bm5r",
  "targets": [
    {
      "id": "cmn5h1vsn010001pv1cjg2n4t",
      "model": "bass",
      "cost": 4,
      "formats": ["wav"],
      "status": "completed",
      "duration": 200.53,
      "output": [
        {
          "name": "bass",
          "format": "wav",
          "link": "https://cdn.audioshake.ai/..."
        }
      ]
    },
    {
      "id": "cmn5h1vsn00zz01pv6xjn3hxd",
      "model": "drums",
      "formats": ["wav"],
      "status": "processing",
      "output": []
    }
  ]
}
```

### Task-level fields

| Field          | Always present       | Description                                                          |
|----------------|----------------------|----------------------------------------------------------------------|
| `id`           | Yes                  | Unique Task identifier                                              |
| `createdAt`    | Yes                  | When the Task was created                                          |
| `completedAt` | No                   | When all targets finished. `null` while any target is still processing.|
| `clientId`     | Yes                  | Your client identifier                                             |
| `assetId`      | Yes*                 | Asset ID of the input file. _Absent if `url` was used._          |
| `url`          | Yes*                 | Input URL. _Absent if `assetId` was used._                       |
| `cost`         | No                   | Total credits consumed across all completed targets. Only present once targets complete.|
| `metadata`     | No                   | Only present if provided in the original request.                 |

### Target fields

| Field   | Always present       | Description                                                        |
|---------|----------------------|--------------------------------------------------------------------|
| `id`    | Yes                  | Unique target identifier                                          |
| `model` | Yes                  | Model that was run                                            |
| `status`| Yes                  | `processing`, `completed`, or `error`                    |
| `formats`| Yes                 | Requested output formats                                |
| `output`| Yes                  | Array of downloadable files. Empty `[]` while processing.| 
| `cost`  | No                   | Credits consumed. Only present when `completed`.            |
| `duration`| No                 | Audio duration processed (seconds). Only present when `completed`.|
| `error`  | No                   | Error object with `code` and `message`. Only present when `error`.|

### Output file fields

| Field   | Description                                                  |
|---------|--------------------------------------------------------------|
| `name`  | Output filename                                            |
| `format`| File format (e.g. `wav`, `json`)                         |
| `link`  | Presigned download URL (expires after 1 hour)            |

## Delivery

- Sent as `POST` with `Content-Type: application/json`
- Your endpoint must return a `2xx` status code promptly
- Output download links expire after one hour — re-fetch the Task for fresh links if needed.