# Builds

> Build a method, steer it with messages, and follow it to the end.

Source: https://docs.fous.com/api-reference/builds
Index: https://docs.fous.com/llms.txt

- `GET /v1/builds`: List builds
- `POST /v1/builds`: Build a method
- `GET /v1/builds/{id}`: Get a build
- `DELETE /v1/builds/{id}`: Dismiss a build
- `POST /v1/builds/{id}/cancel`: Cancel a build
- `POST /v1/builds/{id}/messages`: Message a build
- `GET /v1/builds/{id}/images/{position}`: Get a build image

## The Build object

- `id` (string, required): bld_ followed by 26 characters.
- `status` (string, required): building: still going. ready: method is what it made. requires_auth: it waits for a connected account on the site and goes on by itself once there is one. unsupported: it ended without a method; reason says why. One of `building`, `ready`, `requires_auth`, `unsupported`.
- `kind` (string, required): new: a new method (based_on when it was started from another). change: a change of the method in based_on, which improves its version in place when the contract stays, else makes its next version. repair: Fous repairing a version of your method. One of `new`, `change`, `repair`.
- `effect` (string): What the method does: read gets data; write does something on the site, which the build does once for real. One of `read`, `write`.
- `query` (string, required): The request the builder works on; a follow-up’s also carries the request it goes on from.
- `asked` (string, required): The person’s own words.
- `images` (array of object): The images sent with the request.
  - `url` (string, required): GET it with your key.
- `platform` (string)
- `queue` (object): A change waiting for the one running on the same method (one change at a time per method, repairs first): how many are ahead of it.
  - `ahead` (integer, required)
- `events` (array of object, required): What the build said as it worked, oldest first.
  - `at` (string, required)
  - `kind` (string, required): note: what the builder found or decided, in its own words. status: what it is doing (the latest is the live line). One of `note`, `status`.
  - `message` (string, required)
- `messages` (array of object): What the person sent to the build, oldest first.
  - `at` (string, required)
  - `text` (string, required)
  - `images` (array of object)
    - `url` (string, required): GET it with your key.
  - `seen` (boolean, required): The builder took it in. One it did not take in went on to the next build (next), unless the build had done its action on the site.
- `follows` (string): The build of the same thread this one goes on from.
- `next` (string): The next build of the thread: messages this one did not take in went on there.
- `reason` (string): Why it ended as it did, in a plain sentence; for a version your organization is not on, what it changes and how to switch.
- `outcome` (object): Once ended, what the build made: improved (the version revised in place, for everyone using it), new_version, new_method, already_done (the version already does this; free) or repaired.
  - `type` (string, required): One of `improved`, `new_version`, `new_method`, `already_done`, `repaired`.
  - `version` (integer)
- `may_have_run` (boolean): A write build ended unsure whether its action reached the site: check there before asking again.
- `based_on` (object): The method and version it changes or was started from.
  - `id` (string, required)
  - `slug` (string, required)
  - `name` (string, required)
  - `version` (integer): The version, when one is meant.
- `method` ([Method](https://docs.fous.com/api-reference/methods.md#the-method-object))
- `performed` (boolean): A write build did the action once, for real.
- `result` (object): performed: what the site answered.
  - `data` (JSON value)
- `estimate` (object): While building: how long recent builds took. low_seconds to high_seconds is the middle half; median_seconds is the middle one.
  - `low_seconds` (integer)
  - `high_seconds` (integer)
  - `median_seconds` (integer)
  - `samples` (integer)
- `created_at` (string, required)
- `completed_at` (string)

```json
{
  "id": "bld_01m5kz8x0vb6dp3jq2w4e5r6t7",
  "status": "ready",
  "kind": "new",
  "effect": "read",
  "query": "Search Rust crates by keyword",
  "asked": "Search Rust crates by keyword",
  "platform": "crates.io",
  "events": [
    {
      "at": "2026-10-23T08:40:21.000Z",
      "kind": "note",
      "message": "The search page reads its results from a JSON endpoint that takes the keyword."
    },
    {
      "at": "2026-10-23T08:40:34.000Z",
      "kind": "status",
      "message": "Testing the method with two keywords."
    }
  ],
  "created_at": "2026-10-23T08:40:02.000Z",
  "method": {
    "id": "mth_01m5kz9a1b2c3d4e5f6g7h8j9k",
    "slug": "crates.io/search_crates",
    "name": "Search crates",
    "description": "Searches crates.io by keyword.",
    "returns": "name, description, downloads, version",
    "platform": {
      "name": "crates.io",
      "domain": "crates.io"
    },
    "input_schema": {
      "type": "object",
      "required": [
        "query"
      ],
      "properties": {
        "query": {
          "type": "string",
          "description": "Keyword."
        }
      }
    },
    "effect": "read",
    "auth": {
      "required": false
    },
    "cost": {
      "credits": 1
    },
    "version": 1,
    "latest_version": 1,
    "private": true
  },
  "completed_at": "2026-10-23T08:41:12.000Z"
}
```

## List builds

`GET https://api.fous.com/v1/builds`

Your organization’s 50 newest builds of the past 30 days, newest first, with the repairs of its methods; dismissed ones are left out. Free.

### Returns

- `200`: The builds.

The answer has these fields:

- `builds` ([array of Build](https://docs.fous.com/api-reference/builds.md#the-build-object), required)

### Example request

```bash
curl 'https://api.fous.com/v1/builds' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "builds": [
    {
      "id": "bld_01m5kz8x0vb6dp3jq2w4e5r6t7",
      "status": "ready",
      "kind": "new",
      "effect": "read",
      "query": "Search Rust crates by keyword",
      "asked": "Search Rust crates by keyword",
      "platform": "crates.io",
      "events": [
        {
          "at": "2026-10-23T08:40:21.000Z",
          "kind": "note",
          "message": "The search page reads its results from a JSON endpoint that takes the keyword."
        },
        {
          "at": "2026-10-23T08:40:34.000Z",
          "kind": "status",
          "message": "Testing the method with two keywords."
        }
      ],
      "created_at": "2026-10-23T08:40:02.000Z",
      "method": {
        "id": "mth_01m5kz9a1b2c3d4e5f6g7h8j9k",
        "slug": "crates.io/search_crates",
        "name": "Search crates",
        "description": "Searches crates.io by keyword.",
        "returns": "name, description, downloads, version",
        "platform": {
          "name": "crates.io",
          "domain": "crates.io"
        },
        "input_schema": {
          "type": "object",
          "required": [
            "query"
          ],
          "properties": {
            "query": {
              "type": "string",
              "description": "Keyword."
            }
          }
        },
        "effect": "read",
        "auth": {
          "required": false
        },
        "cost": {
          "credits": 1
        },
        "version": 1,
        "latest_version": 1,
        "private": true
      },
      "completed_at": "2026-10-23T08:41:12.000Z"
    }
  ]
}
```

## Build a method

`POST https://api.fous.com/v1/builds`

Builds a method for one capability, on the site you name or on the sources that answer it best (merged when several have it), usually in about a minute (a site that is harder to read can take a few). A build makes a new method of your organization, public unless you send visibility private (anyone can find and run a public one, with their own accounts): search is where existing methods are found. With method it changes that method (any public one, or your own; @N starts from one version, else the latest): a change that keeps its inputs and outputs improves the version in place, for everyone using it, free, and only when it still answers the saved inputs at least as well; one that changes them makes the next version; a different capability, visibility private on another organization’s method, or a change by a non-owner to a method that signs in or acts makes a method of your own, based on it. One change at a time runs per method (queue says how many are ahead); a request the version already does ends at once with outcome already_done, free. Steer it with POST /v1/builds/{id}/messages. A public build is free within the plan’s monthly allowance, then 100 credits; a private one always costs 100 credits; a build that makes no new method is free.

### Request body

Required, JSON.

- `query` (string, required): What the method should read or do, in plain words.
- `platform` (string): The website (a domain); without it the builder picks the sources.
- `input` (object): Values to build with: the first test input. A write build does the action once for real, with these values or made-up ones.
- `input_schema` (object): The inputs you want the method to take, as a JSON Schema object.
- `output_schema` (object): The fields you want back, as a JSON Schema object.
- `method` (string): A method id or slug to change (@N: from that version): improved in place, its next version, or a method of your own from it.
- `images` (array of object): Up to 4 pictures that show what you mean (PNG, JPEG, WebP or GIF), 2.5 MB in all: each {"url"} (a public https address Fous reads) or {"media_type", "data"} (base64).
- `visibility` (string): Required for a new method (without method). public: anyone can find and run it, with their own accounts. private: only your organization, for 100 credits; on another organization’s method it makes a method of your own. A new method made from one of your private methods is private unless you send public. One of `public`, `private`.
- `connections` (array of string): The connections (logins or API keys, on any sites) the build may use: on each site it signs in to, the one of that site; an empty list builds without any. Without it, the site’s default login.

### Returns

A [Build](https://docs.fous.com/api-reference/builds.md#the-build-object) object.

- `200`: The same request already waits for a connected account (requires_auth); it goes on by itself once there is one.
- `202`: Building: a new build, the same request already running (joined), or the change already running on that method, which takes this request as a message. Poll GET /v1/builds/{id}. The same Build, with status "building".

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | Invalid body or schema |
| 402 | `insufficient_credits` | Allowance used and not enough credits |
| 403 | `forbidden` | Only owners and admins build |
| 404 | `not_found` | No method to start from, or no such version of it |
| 413 | `invalid_request` | The body is over 4 MB |
| 422 | `not_buildable`, `request_refused` | No website, app, account or API is involved (not_buildable), or the request check turned it away (request_refused, with its verdict as reason) |
| 429 | `rate_limited` | Too many requests for the plan this minute |
| 503 | `service_unavailable` | The builder or billing is briefly unavailable; nothing was charged |

### Example request

```bash
curl 'https://api.fous.com/v1/builds' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Search Rust crates by keyword",
    "platform": "crates.io",
    "visibility": "public"
  }'
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/builds' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Search Rust crates by keyword",
    "platform": "crates.io",
    "input": {
      "country": "Germany",
      "year": 2027
    },
    "input_schema": {
      "type": "object",
      "required": [
        "country"
      ],
      "properties": {
        "year": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9999,
          "description": "Calendar year, for example 2026. Defaults to the current year."
        },
        "country": {
          "type": "string",
          "description": "Country name or two-letter country code, for example Germany or DE."
        }
      }
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "country_name": {
          "type": "string"
        },
        "year": {
          "type": "integer"
        },
        "holidays": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "method": "date.nager.at/list_public_holidays",
    "images": [
      {
        "url": "https://example.com"
      }
    ],
    "visibility": "public",
    "connections": [
      "conn_01m5k2v8c4n6p8r0t2w4y6a8c0"
    ]
  }'
```

### Response 202

```json
{
  "id": "bld_01m5kz8x0vb6dp3jq2w4e5r6t7",
  "status": "building",
  "kind": "new",
  "effect": "read",
  "query": "Search Rust crates by keyword",
  "asked": "Search Rust crates by keyword",
  "platform": "crates.io",
  "events": [],
  "estimate": {
    "low_seconds": 52,
    "high_seconds": 104,
    "median_seconds": 71,
    "samples": 100
  },
  "created_at": "2026-10-23T08:40:02.000Z"
}
```

### Response 200

```json
{
  "id": "bld_01m5kz8x0vb6dp3jq2w4e5r6t7",
  "status": "requires_auth",
  "kind": "new",
  "effect": "read",
  "query": "List my starred repositories on github.com",
  "asked": "List my starred repositories on github.com",
  "platform": "github.com",
  "events": [],
  "created_at": "2026-10-23T08:40:02.000Z",
  "reason": "This needs a signed-in github.com account. Connect one, and the build goes on.",
  "completed_at": "2026-10-23T08:40:31.000Z"
}
```

### Error 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "query: Too small: expected string to have >=5 characters",
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Get a build

`GET https://api.fous.com/v1/builds/{id}`

The build: its status, what it said as it worked (events), the messages sent to it, and the method once ready. requires_auth means the site needs a connected account first. Free.

### Path parameters

- `id` (string, required)

### Query parameters

- `wait` (integer): Seconds to hold the answer while it is still running, 0 to 60. Default 0.
- `after` (integer): The number of events you have: a wait ends as soon as there are more.

### Returns

A [Build](https://docs.fous.com/api-reference/builds.md#the-build-object) object.

- `200`: Finished.
- `202`: Still building. The same Build, with status "building".

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | No such build |

### Example request

```bash
curl 'https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7?wait=30&after=1' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "id": "bld_01m5kz8x0vb6dp3jq2w4e5r6t7",
  "status": "ready",
  "kind": "new",
  "effect": "read",
  "query": "Search Rust crates by keyword",
  "asked": "Search Rust crates by keyword",
  "platform": "crates.io",
  "events": [
    {
      "at": "2026-10-23T08:40:21.000Z",
      "kind": "note",
      "message": "The search page reads its results from a JSON endpoint that takes the keyword."
    },
    {
      "at": "2026-10-23T08:40:34.000Z",
      "kind": "status",
      "message": "Testing the method with two keywords."
    }
  ],
  "created_at": "2026-10-23T08:40:02.000Z",
  "method": {
    "id": "mth_01m5kz9a1b2c3d4e5f6g7h8j9k",
    "slug": "crates.io/search_crates",
    "name": "Search crates",
    "description": "Searches crates.io by keyword.",
    "returns": "name, description, downloads, version",
    "platform": {
      "name": "crates.io",
      "domain": "crates.io"
    },
    "input_schema": {
      "type": "object",
      "required": [
        "query"
      ],
      "properties": {
        "query": {
          "type": "string",
          "description": "Keyword."
        }
      }
    },
    "effect": "read",
    "auth": {
      "required": false
    },
    "cost": {
      "credits": 1
    },
    "version": 1,
    "latest_version": 1,
    "private": true
  },
  "completed_at": "2026-10-23T08:41:12.000Z"
}
```

### Response 202

```json
{
  "id": "bld_01m5kz8x0vb6dp3jq2w4e5r6t7",
  "status": "building",
  "kind": "new",
  "effect": "read",
  "query": "Search Rust crates by keyword",
  "asked": "Search Rust crates by keyword",
  "platform": "crates.io",
  "events": [
    {
      "at": "2026-10-23T08:40:21.000Z",
      "kind": "note",
      "message": "The search page reads its results from a JSON endpoint that takes the keyword."
    },
    {
      "at": "2026-10-23T08:40:34.000Z",
      "kind": "status",
      "message": "Testing the method with two keywords."
    }
  ],
  "estimate": {
    "low_seconds": 52,
    "high_seconds": 104,
    "median_seconds": 71,
    "samples": 100
  },
  "created_at": "2026-10-23T08:40:02.000Z"
}
```

### Error 404

```json
{
  "error": {
    "code": "not_found",
    "message": "No such build.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Dismiss a build

`DELETE https://api.fous.com/v1/builds/{id}`

Takes a finished build off the list; the method it made stays. A build waiting for a connected account ends. Free.

### Path parameters

- `id` (string, required)

### Returns

- `200`: Dismissed.

The answer has these fields:

- `id` (string)
- `dismissed` (boolean)

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | No such build |
| 409 | `conflict` | Still building |

### Example request

```bash
curl 'https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7' \
  -X DELETE \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Response 200

```json
{
  "id": "bld_01m5kz8x0vb6dp3jq2w4e5r6t7",
  "dismissed": true
}
```

### Error 404

```json
{
  "error": {
    "code": "not_found",
    "message": "No such build.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Cancel a build

`POST https://api.fous.com/v1/builds/{id}/cancel`

Cancels a build that is still going: it ends with the reason "Stopped." and nothing is charged for it. A write build that already sent its action says so. Free.

### Path parameters

- `id` (string, required)

### Returns

A [Build](https://docs.fous.com/api-reference/builds.md#the-build-object) object.

- `200`: Stopped.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | No such build |
| 409 | `conflict` | Already ended |

### Example request

```bash
curl 'https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/cancel' \
  -X POST \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Error 404

```json
{
  "error": {
    "code": "not_found",
    "message": "No such build.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Message a build

`POST https://api.fous.com/v1/builds/{id}/messages`

Sends a message to a build, checked like a build request. A running build takes it at its next step (202 with the same build; seen turns true once it has). After the build ended, the message starts the next build of the thread: a change to the method it made, or the request again with the message (a new build whose follows names this one, priced as a build).

### Path parameters

- `id` (string, required)

### Request body

Required, JSON.

- `text` (string, required): Your message, in plain words.
- `images` (array of object): Up to 4 pictures that go with it, 2.5 MB in all: each {"url"} (a public https address) or {"media_type", "data"} (base64).

### Returns

A [Build](https://docs.fous.com/api-reference/builds.md#the-build-object) object.

- `200`: The next build of the thread waits for a connected account (requires_auth).
- `202`: The running build takes it at its next step, or the next build of the thread started. The same Build, with status "building".

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | Invalid body |
| 402 | `insufficient_credits` | Allowance used and not enough credits |
| 403 | `forbidden` | Only owners and admins change builds |
| 404 | `not_found` | No such build |
| 413 | `invalid_request` | The body is over 4 MB |
| 422 | `not_buildable`, `request_refused` | No website, app, account or API is involved (not_buildable), or the request check turned it away (request_refused, with its verdict as reason) |
| 429 | `rate_limited` | Too many requests for the plan this minute |
| 503 | `service_unavailable` | The builder or billing is briefly unavailable; nothing was charged |

### Example request

```bash
curl 'https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/messages' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Also return each crate’s license."
  }'
```

With every optional parameter:

```bash
curl 'https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/messages' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Also return each crate’s license.",
    "images": [
      {
        "url": "https://example.com"
      }
    ]
  }'
```

### Response 202

```json
{
  "id": "bld_01m5kz8x0vb6dp3jq2w4e5r6t7",
  "status": "building",
  "kind": "new",
  "effect": "read",
  "query": "Search Rust crates by keyword",
  "asked": "Search Rust crates by keyword",
  "platform": "crates.io",
  "events": [
    {
      "at": "2026-10-23T08:40:21.000Z",
      "kind": "note",
      "message": "The search page reads its results from a JSON endpoint that takes the keyword."
    },
    {
      "at": "2026-10-23T08:40:34.000Z",
      "kind": "status",
      "message": "Testing the method with two keywords."
    }
  ],
  "estimate": {
    "low_seconds": 52,
    "high_seconds": 104,
    "median_seconds": 71,
    "samples": 100
  },
  "created_at": "2026-10-23T08:40:02.000Z",
  "messages": [
    {
      "at": "2026-10-23T08:40:40.000Z",
      "text": "Also return each crate’s license.",
      "seen": false
    }
  ]
}
```

### Error 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "text: Too small: expected string to have >=1 characters",
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Get a build image

`GET https://api.fous.com/v1/builds/{id}/images/{position}`

An image sent with a build request or a message, by its position (the url in images names it). Free.

### Path parameters

- `id` (string, required)
- `position` (integer, required)

### Returns

The file, as `image/*`.

- `200`: The image.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `not_found` | No such image |

### Example request

```bash
curl 'https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/images/0' \
  -H "Authorization: Bearer $FOUS_API_KEY"
```

### Error 404

```json
{
  "error": {
    "code": "not_found",
    "message": "No such image.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```