Builds | Fous API Reference

The Build object

idstringrequired
bld_ followed by 26 characters.
statusstringrequired
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.
buildingreadyrequires_authunsupported
kindstringrequired
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.
newchangerepair
effectstring
What the method does: read gets data; write does something on the site, which the build does once for real.
readwrite
querystringrequired
The request the builder works on; a follow-up’s also carries the request it goes on from.
askedstringrequired
The person’s own words.
imagesarray of object
The images sent with the request.
Show child attributesHide child attributes
- urlstringrequired
  GET it with your key.
platformstring
queueobject
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.
Show child attributesHide child attributes
- aheadintegerrequired
eventsarray of objectrequired
What the build said as it worked, oldest first.
Show child attributesHide child attributes
- atstringrequired
- kindstringrequired
  note: what the builder found or decided, in its own words. status: what it is doing (the latest is the live line).
  notestatus
- messagestringrequired
messagesarray of object
What the person sent to the build, oldest first.
Show child attributesHide child attributes
- atstringrequired
- textstringrequired
- imagesarray of object
  Show child attributesHide child attributes
  - urlstringrequired
    GET it with your key.
- seenbooleanrequired
  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.
followsstring
The build of the same thread this one goes on from.
nextstring
The next build of the thread: messages this one did not take in went on there.
reasonstring
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.
outcomeobject
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.
Show child attributesHide child attributes
- typestringrequired
  improvednew_versionnew_methodalready_donerepaired
- versioninteger
may_have_runboolean
A write build ended unsure whether its action reached the site: check there before asking again.
based_onobject
The method and version it changes or was started from.
Show child attributesHide child attributes
- idstringrequired
- slugstringrequired
- namestringrequired
- versioninteger
  The version, when one is meant.
methodMethod
performedboolean
A write build did the action once, for real.
resultobject
performed: what the site answered.
Show child attributesHide child attributes
- dataJSON value
estimateobject
While building: how long recent builds took. low_seconds to high_seconds is the middle half; median_seconds is the middle one.
Show child attributesHide child attributes
- low_secondsinteger
- high_secondsinteger
- median_secondsinteger
- samplesinteger
created_atstringrequired
completed_atstring

Build

{  "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

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

200The builds.

The answer has these fields:

buildsarray of Buildrequired

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/builds', {  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.get(    "https://api.fous.com/v1/builds",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

Response 200

{  "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"    }  ]}

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.

querystringrequired
What the method should read or do, in plain words.
platformstringOptional
The website (a domain); without it the builder picks the sources.
inputobjectOptional
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_schemaobjectOptional
The inputs you want the method to take, as a JSON Schema object.
output_schemaobjectOptional
The fields you want back, as a JSON Schema object.
methodstringOptional
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.
imagesarray of objectOptional
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).
visibilitystringOptional
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.
publicprivate
connectionsarray of stringOptional
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 object.

200The same request already waits for a connected account (requires_auth); it goes on by itself once there is one.
202Building: 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_buildablerequest_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

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"  }'

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/builds', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    query: 'Search Rust crates by keyword',    platform: 'crates.io',    visibility: 'public'  }),});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.post(    "https://api.fous.com/v1/builds",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    json={        "query": "Search Rust crates by keyword",        "platform": "crates.io",        "visibility": "public"    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "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"}

{  "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": {    "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

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

idstringrequired

Query parameters

waitintegerdefault 0Optional
Seconds to hold the answer while it is still running, 0 to 60.
afterintegerOptional
The number of events you have: a wait ends as soon as there are more.

Returns

A Build object.

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

Errors

Status	Code	When
404	`not_found`	No such build

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7', {  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.get(    "https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "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"}

{  "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": {    "code": "not_found",    "message": "No such build.",    "doc_url": "https://docs.fous.com/guides/errors#not_found",    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"  }}

Dismiss a build

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

Path parameters

idstringrequired

Returns

200Dismissed.

The answer has these fields:

idstring
dismissedboolean

Errors

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

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7', {  method: 'DELETE',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.delete(    "https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

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

{  "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

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

idstringrequired

Returns

A Build object.

200Stopped.

Errors

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

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/cancel', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.post(    "https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/cancel",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

Response 404

{  "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

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

idstringrequired

Request body

Required, JSON.

textstringrequired
Your message, in plain words.
imagesarray of objectOptional
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 object.

200The next build of the thread waits for a connected account (requires_auth).
202The 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_buildablerequest_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

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."  }'

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/messages', {  method: 'POST',  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,    'Content-Type': 'application/json',  },  body: JSON.stringify({    text: 'Also return each crate’s license.'  }),});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.post(    "https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/messages",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    json={        "text": "Also return each crate’s license."    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

{  "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": {    "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

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

Path parameters

idstringrequired
positionintegerrequired

Returns

The file, as image/*.

200The image.

Errors

Status	Code	When
404	`not_found`	No such image

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

// Save as fous.mts, then run: npx tsx fous.mtsconst response = await fetch('https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/images/0', {  headers: {    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,  },});const result = await response.json();if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);console.log(result);

import osimport requestsresponse = requests.get(    "https://api.fous.com/v1/builds/bld_01m5kz8x0vb6dp3jq2w4e5r6t7/images/0",    headers={        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",    },    timeout=180,)result = response.json()if not response.ok:    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")print(result)

Sent with your key, kept for this tab only. A run uses credits like any call.

Response 404

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