# Build or edit a tool

> Build, edit or customize a tool, with explicit live-test authorization when the managed notice is active.

Source: https://docs.fous.com/api-reference/createBuild

`POST /v1/builds`

Describe the data or action you need from a website and Fous explores it, builds the tool, verifies it with real runs and publishes it to your organization. Answers 202 with the build at once; poll GET /v1/builds/{build_id}?wait=170 until status is ready, failed or cancelled (a few minutes). With network sharing on, builds are free within the plan’s monthly allowance: 20 on pay-as-you-go, 50 on Plus and 100 on Pro, per UTC calendar month. Beyond the allowance, or with sharing off, a build costs 100 credits, charged when ready. Failed, cancelled or reused builds release unexpired reservations and do not count toward the allowance. Send Idempotency-Key to make the submission safe to repeat. Needs tools:write.

Authentication: `Authorization: Bearer $FOUS_API_KEY`.

## Headers

- `Idempotency-Key` (string): The same key with the same body returns the same build.

## Request body

Required. JSON.

- `risk_acknowledgment` (BuildRiskAcknowledgment): Required once a managed build notice is active. A missing or outdated acknowledgment returns 409 risk_acknowledgment_required with the exact current notice in error.details.notice. Present its full text and affirmation and obtain explicit authorization before each build, edit or user-requested retry, then send its version. Live tests and repairs can perform repeated real actions. Never infer authorization from a request to build a tool.
- `prompt` (string, required): What the tool should return or do, in plain words. Name the website.
- `url` (string): A page to start from.
- `urls` (array of string): Pages to start from, when you know them.
- `api` (string): Edit this tool of yours instead of building a new one.
- `method_id` (integer): With api: customize this public method as your organization’s own.
- `connections` (object): Connected accounts the tool signs in with: alias → connection id.
- `environment` (object): Keys the tool needs, by name → value (an .env). Saved with the tool, never returned.
- `visibility` (string): private (the default) keeps the tool to your organization. One of "private", "public".
- `contribute` (boolean): Let Fous publish a general version to the network after ten runs. Eligible for the plan’s monthly free-build allowance; beyond it, a build costs 100 credits. Defaults to the organization’s setting.
- `idempotency_key` (string): Optional; the Idempotency-Key header does the same.

## Response 202

Admitted; or the build this Idempotency-Key already started

- `success` (true, required)
- `data` (Build, required): A build: from queued through exploring, compiling, verifying and publishing to ready, failed or cancelled. Once ready, api names the tool and method its operation; prepared_request carries an input the builder verified it with.

## Errors

Every error uses the Error schema: branch on `error.code`. Codes are listed at https://docs.fous.com/guides/errors.

- 400
- 401 (headers: WWW-Authenticate)
- 402
- 403
- 404
- 408
- 409
- 410
- 413
- 422
- 429 (headers: Retry-After)
- 500
- 502
- 503 (headers: Retry-After)
- 504

## Example request

```bash
curl 'https://api.fous.com/v1/builds' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Idempotency-Key: $FOUS_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Flight prices between two airports on a date from kayak.com","urls":["https://www.kayak.com"]}'
```