{"openapi":"3.1.0","info":{"title":"Fous API","version":"1.0.0","description":"Search website methods (one capability each, on one site or merged from several) and run them (manual), send a query in plain words and Fous picks and runs the methods (auto), or build a new one. Search is free; a run costs 1 credit; a query costs 5; failures are free; public builds are free within the plan’s monthly allowance, then 100 credits; a private build costs 100 credits. 1 credit = $0.01. The same capabilities are MCP tools at /mcp."},"externalDocs":{"description":"Documentation index for agents","url":"https://docs.fous.com/llms.txt"},"servers":[{"url":"https://api.fous.com"}],"security":[{"bearer":[]}],"tags":[{"name":"Methods","description":"Find methods, read their contracts, publish or delete your own."},{"name":"Runs","description":"Run a method with your own input, or send a query and get the result."},{"name":"Builds","description":"Build a method, steer it with messages, and follow it to the end."},{"name":"Connections","description":"Website logins and API keys that methods run with."},{"name":"Account","description":"The organization behind the key."}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A Fous API key (fous_sk_…), sent as Authorization: Bearer."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","forbidden","insufficient_scope","insufficient_credits","connection_required","not_found","request_timeout","conflict","invalid_input","request_refused","not_buildable","rate_limited","server_error","upstream_error","upstream_blocked","method_unavailable","method_repairing","upstream_timeout","service_unavailable"],"description":"Stable code to branch on."},"message":{"type":"string","description":"What happened, in one or two plain sentences."},"next_step":{"type":"string","description":"What to do now, in one sentence."},"doc_url":{"type":"string","description":"This code’s entry in the errors guide (a policy refusal: the policy)."},"request_id":{"type":"string","description":"The X-Request-Id of this request: quote it to support."},"reason":{"type":"string","description":"A finer cause when one helps: site_rate_limited, spend_limit, not_owned, stopped, body_too_large, sign_in_busy, step_expired, or (request_refused) the request check’s verdict: unclear, unsupported, explicit, harmful, platform_probe, refused."},"retryable":{"type":"boolean","description":"On a failed run: whether trying again can help (a block, a slow or failing site)."},"may_have_run":{"type":"boolean","description":"A method with side effects failed after its request reached the site: check the site before running it again."},"retry_after":{"type":"integer","description":"Seconds to wait before trying again: the plan’s (rate_limited, with Retry-After), Fous’s (service_unavailable) or the site’s, when it said."},"param":{"type":"string","description":"The parameter at fault: input.<name> for an input, method for a method."},"errors":{"type":"array","description":"invalid_input: every input that does not fit, all at once. A required input that a misspelled name was meant for is listed as missing too; the message counts the two once.","items":{"type":"object","required":["field","problem","message"],"properties":{"field":{"type":"string"},"problem":{"type":"string","enum":["unknown","missing","type","enum","range","invalid"]},"message":{"type":"string"},"did_you_mean":{"type":"string","description":"unknown: the input it most likely meant."},"expected":{"type":"string","description":"type: the type it takes."},"allowed":{"type":"array","items":{},"description":"enum: the values it takes."}}}},"method":{"type":"string","description":"invalid_input: the method whose inputs these are."},"input_schema":{"type":"object","description":"invalid_input: the method’s own input_schema, exactly as stored."},"example":{"description":"invalid_input: a call that fits ({method, input}), from the method’s saved example (a write method’s is built from its schema). request_refused (unclear) and not_buildable: a request phrased so it can be built."},"did_you_mean":{"type":"string","description":"not_found: the method slug it most likely meant."},"suggestions":{"type":"array","items":{"type":"object"},"description":"not_found: methods close to the name ({id, slug, name, summary})."},"alternatives":{"type":"array","items":{"type":"object"},"description":"method_repairing: methods that do the same."},"version":{"type":"integer","description":"method_repairing: the version under repair."},"latest_version":{"type":"integer","description":"method_repairing: the method’s newest version; not_found for a version: the newest one there is."},"repair":{"type":"object","description":"method_repairing: when the version is expected back.","properties":{"expected_at":{"type":"string","format":"date-time"},"back_in_minutes":{"type":"integer"}}},"connect":{"type":"object","description":"connection_required: the platform and connection type to connect, and connection_id when your organization already has a connection for the site.","properties":{"platform":{"type":"string"},"type":{"type":"string","enum":["session","api_key"]},"connection_id":{"type":"string"},"status":{"type":"string","enum":["pending","active","needs_attention"],"description":"The status of your connection, when you have one."}}},"connect_url":{"type":"string","description":"connection_required: the Fous Studio page where a person connects the account (your connection for the site, or a new one). A login also signs in with POST /v1/connections/{id}/sign-in."},"attestation":{"type":"object","description":"invalid_request without attest: true: the notice the person confirms before an account is connected or signed in."},"billing_url":{"type":"string","description":"insufficient_credits: where to add credits."},"available_credits":{"type":"number","description":"insufficient_credits: the credits the organization has."},"required_credits":{"type":"integer","description":"insufficient_credits: what the run, query or build costs."},"private":{"type":"boolean","description":"insufficient_credits on a build: a private method, which always costs credits."},"free_builds":{"type":"object","description":"insufficient_credits on a build: the month’s free builds.","properties":{"used":{"type":"integer"},"allowance":{"type":"integer"},"resets_at":{"type":"string","format":"date-time"}}},"spend_limit":{"type":"object","description":"insufficient_credits with reason spend_limit: the monthly limit, what was spent, in credits, and when it resets.","properties":{"limit":{"type":"number"},"spent":{"type":"number"},"resets_at":{"type":"string","format":"date-time"}}},"limit":{"type":"object","description":"rate_limited: the plan limit met, and its value when the plan sets one.","properties":{"kind":{"type":"string","enum":["requests_per_minute","concurrent_runs","searches_per_minute"]},"value":{"type":"integer"}}},"run_id":{"type":"string","description":"The failed run (failures are free)."},"steps":{"type":"array","items":{"type":"object"},"description":"A failed query: the method calls it made and how each ended."}},"additionalProperties":true}}},"InputSchema":{"type":"object","description":"A flat JSON Schema object: snake_case properties with descriptions; required lists the inputs a call must send.","additionalProperties":true},"Auth":{"type":"object","required":["required"],"properties":{"required":{"type":"boolean","description":"Whether the method runs with a connected account."},"type":{"type":"string","enum":["session","api_key"],"description":"session: a website login; api_key: the site’s own API key."},"connection":{"type":["string","null"],"description":"Your default connection for this platform, if any."}}},"MethodRef":{"type":"object","required":["id","slug","name"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"version":{"type":"integer","description":"The version, when one is meant."}}},"MethodStats":{"type":"object","description":"How the method has done so far.","properties":{"success_rate":{"type":["number","null"]},"runs":{"type":"integer"},"last_success_at":{"type":["string","null"]}}},"Method":{"type":"object","required":["id","slug","name","description","returns","platform","input_schema","effect","auth","cost","version","latest_version"],"properties":{"id":{"type":"string","description":"mth_ followed by 26 characters."},"slug":{"type":"string","description":"<domain>/<snake_case_name>, one method’s own; accepted wherever an id is."},"name":{"type":"string"},"description":{"type":"string"},"returns":{"type":"string","description":"What the output holds, in a few words."},"platform":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}}},"input_schema":{"$ref":"#/components/schemas/InputSchema"},"auth":{"$ref":"#/components/schemas/Auth"},"effect":{"type":"string","enum":["read","write"],"description":"read: it gets data. write: it does something on the site (submits, posts, books, sends); run it with care."},"cost":{"type":"object","properties":{"credits":{"type":"integer"}}},"private":{"type":"boolean","description":"Present (true) on your organization’s methods that are not published."},"version":{"type":"integer","description":"The version shown: the one your organization uses (its pin, else the latest), or the one the ref named (@N). A version is a contract: its inputs and outputs never change."},"latest_version":{"type":"integer","description":"The method’s newest version."},"status":{"type":"string","enum":["degraded","repairing"],"description":"In a search result, present only when the version is not ready: degraded (failing: its saved examples stopped answering, and no run has answered since; runs are still attempted, and Fous repairs it) or repairing (a repair confirmed the break while runs failed too; runs are refused with 503 method_repairing until it ends, at the latest at repair.expected_at)."},"repair":{"type":"object","description":"Only while repairing: when the version is back at the latest. A repair that has not confirmed a break is never shown.","required":["expected_at","back_in_minutes"],"properties":{"expected_at":{"type":"string","format":"date-time"},"back_in_minutes":{"type":"integer"}}},"last_repair":{"type":"object","description":"While degraded, when a repair ran and could not fix the version: when it ended and why, in its own words. Fous checks the version every hour and repairs it again later.","required":["at","reason"],"properties":{"at":{"type":"string","format":"date-time"},"reason":{"type":"string","example":"Fous could not get the method working again; it stays as it is."}}},"deletes_at":{"type":"string","format":"date-time","description":"A public method nobody has run for 6 months: when it is deleted unless it runs (any run keeps it)."}}},"MethodDetail":{"type":"object","required":["id","slug","name","description","returns","platform","input_schema","effect","auth","cost","version","latest_version","revision","pinned_version","status","versions","visibility","output_schema","stats","owned"],"properties":{"id":{"type":"string","description":"mth_ followed by 26 characters."},"slug":{"type":"string","description":"<domain>/<snake_case_name>, one method’s own; accepted wherever an id is."},"name":{"type":"string"},"description":{"type":"string"},"returns":{"type":"string","description":"What the output holds, in a few words."},"platform":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}}},"input_schema":{"$ref":"#/components/schemas/InputSchema"},"auth":{"$ref":"#/components/schemas/Auth"},"effect":{"type":"string","enum":["read","write"],"description":"read: it gets data. write: it does something on the site (submits, posts, books, sends); run it with care."},"cost":{"type":"object","properties":{"credits":{"type":"integer"}}},"private":{"type":"boolean","description":"Present (true) on your organization’s methods that are not published."},"version":{"type":"integer","description":"The version shown: the one your organization uses (its pin, else the latest), or the one the ref named (@N). A version is a contract: its inputs and outputs never change."},"latest_version":{"type":"integer","description":"The method’s newest version."},"status":{"type":"string","enum":["ready","degraded","repairing"],"description":"How the version shown stands: ready (any answer with data makes it ready at once); degraded (failing: its saved examples stopped answering, and no run has answered since; runs are still attempted, and Fous repairs it); repairing (a repair confirmed the break while runs failed too; runs are refused with 503 method_repairing until it ends, at the latest at repair.expected_at)."},"repair":{"type":"object","description":"Only while repairing: when the version is back at the latest. A repair that has not confirmed a break is never shown.","required":["expected_at","back_in_minutes"],"properties":{"expected_at":{"type":"string","format":"date-time"},"back_in_minutes":{"type":"integer"}}},"last_repair":{"type":"object","description":"While degraded, when a repair ran and could not fix the version: when it ended and why, in its own words. Fous checks the version every hour and repairs it again later.","required":["at","reason"],"properties":{"at":{"type":"string","format":"date-time"},"reason":{"type":"string","example":"Fous could not get the method working again; it stays as it is."}}},"deletes_at":{"type":"string","format":"date-time","description":"A public method nobody has run for 6 months: when it is deleted unless it runs (any run keeps it)."},"pinned_version":{"type":["integer","null"],"description":"The version your organization uses: set by its first run (owners too), moved by PATCH {\"pinned_version\": N} or by a new version it builds itself. Null until a run."},"visibility":{"type":"string","enum":["public","private"],"description":"private: only your organization finds and runs it. public: anyone may; it stays public, and anyone may improve it."},"stats":{"$ref":"#/components/schemas/MethodStats"},"owned":{"type":"boolean","description":"Your organization built it: it publishes it, and deletes it while it is private."},"based_on":{"$ref":"#/components/schemas/MethodRef","description":"The method (and its version) this one was started from."},"revision":{"type":"integer","description":"How many times the version shown was revised in place (a repair or an improvement that kept its contract); the seen parameter carries it."},"latest_changes":{"type":"string","description":"When the version shown is not the latest: what the latest changes against it, in a sentence or two."},"versions":{"type":"array","description":"The method’s versions, newest first (at most 20).","items":{"type":"object","required":["version","revision","status","created_at","changes"],"properties":{"version":{"type":"integer"},"revision":{"type":"integer"},"latest":{"type":"boolean","enum":[true],"description":"The newest version."},"pinned":{"type":"boolean","enum":[true],"description":"The version your organization uses."},"status":{"type":"string","enum":["ready","degraded","repairing"]},"created_at":{"type":"string"},"revised_at":{"type":"string","description":"When it was last revised in place."},"changes":{"type":"string","description":"What it changes against the version before it; empty for the first."}}}},"output_schema":{"type":"object","description":"The JSON Schema every run’s data follows."},"example":{"type":"object","properties":{"input":{"type":"object"},"output":{}}}}},"MethodListItem":{"type":"object","required":["id","slug","name","description","returns","platform","input_schema","effect","auth","cost","version","latest_version","status","pinned_version","visibility","owned","stats","created_at","updated_at"],"properties":{"id":{"type":"string","description":"mth_ followed by 26 characters."},"slug":{"type":"string","description":"<domain>/<snake_case_name>, one method’s own; accepted wherever an id is."},"name":{"type":"string"},"description":{"type":"string"},"returns":{"type":"string","description":"What the output holds, in a few words."},"platform":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}}},"input_schema":{"$ref":"#/components/schemas/InputSchema"},"auth":{"$ref":"#/components/schemas/Auth"},"effect":{"type":"string","enum":["read","write"],"description":"read: it gets data. write: it does something on the site (submits, posts, books, sends); run it with care."},"cost":{"type":"object","properties":{"credits":{"type":"integer"}}},"private":{"type":"boolean","description":"Present (true) on your organization’s methods that are not published."},"version":{"type":"integer","description":"The version shown: the one your organization uses (its pin, else the latest), or the one the ref named (@N). A version is a contract: its inputs and outputs never change."},"latest_version":{"type":"integer","description":"The method’s newest version."},"status":{"type":"string","enum":["ready","degraded","repairing"],"description":"How the version shown stands: ready (any answer with data makes it ready at once); degraded (failing: its saved examples stopped answering, and no run has answered since; runs are still attempted, and Fous repairs it); repairing (a repair confirmed the break while runs failed too; runs are refused with 503 method_repairing until it ends, at the latest at repair.expected_at)."},"repair":{"type":"object","description":"Only while repairing: when the version is back at the latest. A repair that has not confirmed a break is never shown.","required":["expected_at","back_in_minutes"],"properties":{"expected_at":{"type":"string","format":"date-time"},"back_in_minutes":{"type":"integer"}}},"last_repair":{"type":"object","description":"While degraded, when a repair ran and could not fix the version: when it ended and why, in its own words. Fous checks the version every hour and repairs it again later.","required":["at","reason"],"properties":{"at":{"type":"string","format":"date-time"},"reason":{"type":"string","example":"Fous could not get the method working again; it stays as it is."}}},"deletes_at":{"type":"string","format":"date-time","description":"A public method nobody has run for 6 months: when it is deleted unless it runs (any run keeps it)."},"pinned_version":{"type":["integer","null"],"description":"The version your organization uses: set by its first run (owners too), moved by PATCH {\"pinned_version\": N} or by a new version it builds itself. Null until a run."},"visibility":{"type":"string","enum":["public","private"],"description":"private: only your organization finds and runs it. public: anyone may; it stays public, and anyone may improve it."},"stats":{"$ref":"#/components/schemas/MethodStats"},"owned":{"type":"boolean","description":"Your organization built it: it publishes it, and deletes it while it is private."},"based_on":{"$ref":"#/components/schemas/MethodRef","description":"The method (and its version) this one was started from."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Run":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","description":"run_ followed by 26 characters; results are kept 24 hours."},"status":{"type":"string","enum":["running","completed","partial","failed"],"description":"partial (query): an answer, but not all of what was asked."},"method":{"type":"object","description":"The method and the version that ran.","properties":{"id":{"type":"string"},"slug":{"type":["string","null"]},"version":{"type":"integer"},"latest_version":{"type":"integer","description":"POST /v1/runs: the method’s newest version."}}},"data":{"description":"The result, shaped by the method’s output_schema (query: by your output_schema when you send one)."},"notice":{"type":"string","description":"A completed run that came back empty or incomplete while the version is under repair: it cost nothing, and when the repair is back at the latest."},"empty":{"type":"boolean","description":"The site answered and has nothing for this input (still a success)."},"raw":{"description":"With include_raw: the site’s own response."},"truncated":{"type":"boolean","description":"The answer is not complete: the site had more than the run could read, or the output was over 10 MB and its longest list was cut. missing says what."},"missing":{"type":"array","items":{"type":"string"},"description":"What the answer lacks, in plain words (a source that failed, items that could not be read, pages not read). Only when something is."},"cost":{"type":"object","properties":{"credits":{"type":"integer"}}},"duration_ms":{"type":"integer"},"source":{"type":"string","enum":["methods","live"],"description":"query: methods answered, or a live web search did."},"steps":{"type":"array","items":{"type":"object"},"description":"query: the method calls made (method: id, slug and the version that ran) and their status."},"sources":{"type":"array","items":{"type":"object"},"description":"query, live answers: the pages the data came from."},"uncovered":{"type":"array","items":{"type":"string"},"description":"query: the things asked for that no method provides yet, answered from the live web beside the method calls."},"created_at":{"type":"string","description":"running only."}}},"Build":{"type":"object","required":["id","status","kind","query","asked","events","created_at"],"properties":{"id":{"type":"string","description":"bld_ followed by 26 characters."},"status":{"type":"string","enum":["building","ready","requires_auth","unsupported"],"description":"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."},"kind":{"type":"string","enum":["new","change","repair"],"description":"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."},"effect":{"type":"string","enum":["read","write"],"description":"What the method does: read gets data; write does something on the site, which the build does once for real."},"query":{"type":"string","description":"The request the builder works on; a follow-up’s also carries the request it goes on from."},"asked":{"type":"string","description":"The person’s own words."},"images":{"type":"array","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"GET it with your key."}}},"description":"The images sent with the request."},"platform":{"type":"string"},"queue":{"type":"object","description":"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.","required":["ahead"],"properties":{"ahead":{"type":"integer"}}},"events":{"type":"array","description":"What the build said as it worked, oldest first.","items":{"type":"object","required":["at","kind","message"],"properties":{"at":{"type":"string"},"kind":{"type":"string","enum":["note","status"],"description":"note: what the builder found or decided, in its own words. status: what it is doing (the latest is the live line)."},"message":{"type":"string"}}}},"messages":{"type":"array","description":"What the person sent to the build, oldest first.","items":{"type":"object","required":["at","text","seen"],"properties":{"at":{"type":"string"},"text":{"type":"string"},"images":{"type":"array","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"GET it with your key."}}}},"seen":{"type":"boolean","description":"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":{"type":"string","description":"The build of the same thread this one goes on from."},"next":{"type":"string","description":"The next build of the thread: messages this one did not take in went on there."},"reason":{"type":"string","description":"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":{"type":"object","description":"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.","required":["type"],"properties":{"type":{"type":"string","enum":["improved","new_version","new_method","already_done","repaired"]},"version":{"type":"integer"}}},"may_have_run":{"type":"boolean","description":"A write build ended unsure whether its action reached the site: check there before asking again."},"based_on":{"$ref":"#/components/schemas/MethodRef","description":"The method and version it changes or was started from."},"method":{"$ref":"#/components/schemas/Method"},"performed":{"type":"boolean","description":"A write build did the action once, for real."},"result":{"type":"object","properties":{"data":{}},"description":"performed: what the site answered."},"estimate":{"type":"object","description":"While building: how long recent builds took. low_seconds to high_seconds is the middle half; median_seconds is the middle one.","properties":{"low_seconds":{"type":"integer"},"high_seconds":{"type":"integer"},"median_seconds":{"type":"integer"},"samples":{"type":"integer"}}},"created_at":{"type":"string"},"completed_at":{"type":"string"}}},"Connection":{"type":"object","required":["id","platform","type","status","default"],"properties":{"id":{"type":"string","description":"conn_ followed by 26 characters."},"platform":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"}}},"type":{"type":"string","enum":["session","api_key"],"description":"session: a website login; api_key: the site’s own API key."},"status":{"type":"string","enum":["pending","active","needs_attention"],"description":"pending: not signed in yet. active: runs use it. needs_attention: the site signed it out, or the key stopped working; sign in again (connect_url, or POST /v1/connections/{id}/sign-in)."},"default":{"type":"boolean","description":"Runs on this platform use it unless a call names another."},"hint":{"type":["string","null"],"description":"api_key: the last characters of the saved key."},"account_hint":{"type":["string","null"],"description":"session: the signed-in account, masked."},"connect_url":{"type":"string","description":"session, until active or while it signs in again: a Fous Studio page where a person signs in to this connection."},"sign_in":{"$ref":"#/components/schemas/SignIn"},"sign_in_ended":{"type":"object","description":"A sign-in the call waited on ended without signing in. An account connected before is unchanged.","required":["reason","message"],"properties":{"reason":{"type":"string","enum":["cancelled","expired"]},"message":{"type":"string"}}},"message":{"type":"string","description":"POST /v1/connections for a site whose login is already connected: that this one is the account runs use."},"checked_at":{"type":["string","null"]},"created_at":{"type":"string"}}},"SignIn":{"type":"object","description":"A website sign-in, while it runs and for a while after it failed. Answer its step with POST /v1/connections/{id}/sign-in.","required":["status","message","fields","choices"],"properties":{"status":{"type":"string","enum":["working","input","approval","failed"],"description":"working: Fous is on the site, wait (GET /v1/connections/{id}?wait=). input: the site asks for fields or a choice. approval: the person approves the sign-in on their device or by email, wait. failed: message says why."},"step_id":{"type":"string","description":"input and approval: the step an answer is for."},"message":{"type":"string","description":"What the site asks for, or why it failed, in a sentence for the person."},"code":{"type":"string","description":"approval: the number the site shows, which the person picks on their device."},"rejected":{"type":"boolean","description":"input: true when the website turned down the last answer; message says so and the same fields are asked again."},"fields":{"type":"array","description":"What the site asks for. Values are never stored or returned.","items":{"$ref":"#/components/schemas/SignInField"}},"choices":{"type":"array","description":"input: ways to go on (send one as choice), such as where to send a code.","items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string"},"label":{"type":"string"}}}},"expires_at":{"type":"string","description":"When the sign-in ends unless it moves on."}}},"SignInField":{"type":"object","required":["id","label","type","required"],"properties":{"id":{"type":"string","description":"The key of its value in fields."},"label":{"type":"string","description":"What to ask the person for."},"type":{"type":"string","enum":["email","text","password","code","select","checkbox","link"],"description":"checkbox: true or false. select: one of options’ values. link: a sign-in link the person copies from an email without opening it. Every other type: text."},"required":{"type":"boolean"},"options":{"type":"array","description":"select: the values it takes.","items":{"type":"object","required":["value","label"],"properties":{"value":{"type":"string"},"label":{"type":"string"}}}},"length":{"type":"integer","description":"code: how many characters, when known."}}},"Account":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"credits":{"type":"object","properties":{"balance":{"type":"integer","description":"Whole credits (1 credit = $0.01)."},"balance_usd":{"type":"number","description":"The balance in US dollars."}}},"limits":{"type":"object","description":"The plan’s limits.","properties":{"requests_per_minute":{"type":"integer","description":"Calls a minute, counted apart for runs and queries and for searches, builds and sign-ins."},"concurrent_runs":{"type":"integer","description":"Runs and queries going at once."},"monthly_spend_limit_credits":{"type":["number","null"],"description":"The organization’s monthly spend limit, in credits; null: no limit."}}},"builds":{"type":"object","properties":{"free_per_month":{"type":"integer","description":"Public builds a month that cost nothing."},"used_this_month":{"type":"integer","description":"Builds this month so far."}}},"prices":{"type":"object","description":"What each call costs, in credits.","properties":{"search":{"type":"integer","description":"A search: free."},"run":{"type":"integer","description":"A run that completes."},"query":{"type":"integer","description":"A query that answers."},"build_after_allowance":{"type":"integer","description":"A public build once the month’s free builds are used."},"private_build":{"type":"integer","description":"A private build, always."}}},"key":{"type":"object","description":"The key this call was made with.","properties":{"kind":{"type":"string","enum":["user","agent"],"description":"user: a key created in Fous Studio. agent: a key an agent got by connecting itself."},"name":{"type":"string"},"client_name":{"type":["string","null"],"description":"agent: the agent that connected."},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the key stops working; null: never."},"last_used_at":{"type":["string","null"],"format":"date-time"}}}}}}},"paths":{"/v1/search":{"get":{"operationId":"searchMethods","tags":["Methods"],"summary":"Find methods","description":"Describe what you need in plain language. Returns the methods that fit, best first, each with its effect (read or write) and input schema, or match \"none\". Search never builds: when nothing fits, build one with POST /v1/builds. Free.","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":500},"description":"What you need, in plain language.","example":"public holidays in Germany next year"},{"name":"platform","in":"query","schema":{"type":"string"},"description":"A domain or site name to search within; alone, it lists that site’s methods."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many: 1 to 20 with a query (default 5); a site listed without a query, up to 100 (default 100)."},{"name":"suggest","in":"query","schema":{"type":"boolean","default":false},"description":"Search as someone types: the methods nearest the text so far (its last word may be unfinished), without checking which do it all, so results, suggested: true, and no match or reason. Five a minute for each of the plan’s requests, counted apart from searches."}],"responses":{"200":{"description":"Methods that fit, or none. With suggest=true, the nearest methods.","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Method"}},"match":{"type":"string","enum":["found","none"],"description":"Always sent, except with suggest=true."},"suggested":{"type":"boolean","enum":[true],"description":"With suggest=true: the results are unchecked suggestions."},"related":{"type":"array","items":{"$ref":"#/components/schemas/Method"},"description":"On a miss: methods that do part of what was asked (unchecked when Fous could not check fit just then; reason says so)."},"reason":{"type":"string","description":"On a miss: why nothing fits (a request that names only a topic), that POST /v1/builds can make it, or that Fous could not check fit just then."}}},"example":{"results":[{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","name":"List public holidays","description":"Lists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types.","returns":"date, weekday, English and local names, regions, type, nationwide flag","platform":{"name":"Nager.Date","domain":"nager.at"},"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."}}},"effect":"read","auth":{"required":false},"cost":{"credits":1},"version":2,"latest_version":2}],"match":"found"}}}},"400":{"description":"Neither query nor platform","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Send query, platform, or both.","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"401":{"description":"No valid key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"unauthorized","message":"Send Authorization: Bearer <Fous API key>. Create one in Fous Studio under API keys (https://app.fous.com/keys).","next_step":"Send Authorization: Bearer <key>. Create a key in Fous Studio: https://app.fous.com/keys.","reason":"api_key_required","doc_url":"https://docs.fous.com/guides/errors#unauthorized","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"429":{"description":"Too many searches for the plan this minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many searches for your plan this minute.","next_step":"Retry in 8 seconds.","retry_after":8,"limit":{"kind":"searches_per_minute","value":60},"doc_url":"https://docs.fous.com/guides/errors#rate_limited","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/methods":{"get":{"operationId":"listMethods","tags":["Methods"],"summary":"List your methods","description":"Your organization’s own methods, private and published, the latest change first; or, with ids, any methods it sees, each at the version it uses, for a live re-read of their status. Free.","parameters":[{"name":"platform","in":"query","schema":{"type":"string"},"description":"Only the methods on this site (a domain or site name)."},{"name":"ids","in":"query","schema":{"type":"string"},"description":"Method ids, comma-separated, at most 50: those methods instead of your own (owned says whose)."}],"responses":{"200":{"description":"Your methods.","content":{"application/json":{"schema":{"type":"object","required":["methods"],"properties":{"methods":{"type":"array","items":{"$ref":"#/components/schemas/MethodListItem"}}}},"example":{"methods":[{"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,"status":"ready","pinned_version":1,"visibility":"private","owned":true,"stats":{"success_rate":1,"runs":4,"last_success_at":"2026-10-23T09:02:11.000Z"},"created_at":"2026-10-23T08:41:12.000Z","updated_at":"2026-10-23T08:41:12.000Z"}]}}}}}}},"/v1/methods/{domain}/{name}":{"get":{"operationId":"getMethod","tags":["Methods"],"summary":"Get a method","description":"A method’s full contract at the version your organization uses (or @N for one version): input and output schema, an example, auth, cost, how it stands (status, repair), its versions and what the latest changes. With wait, the answer is held while the version is under repair; with seen (the status:revision:deletes_at of the last read) while nothing about it has changed. Free.","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"The site of the method’s slug.","example":"date.nager.at"},{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"The name of the method’s slug.","example":"list_public_holidays"},{"name":"wait","in":"query","description":"Seconds to hold the answer while the version is under repair (or, with seen, while nothing has changed), 0 to 60.","schema":{"type":"integer","minimum":0,"maximum":60,"default":0}},{"name":"seen","in":"query","schema":{"type":"string"},"description":"What was last read, as <status>:<revision>:<deletes_at or ->; with wait, the answer is held until it differs.","example":"repairing:2:-"}],"responses":{"200":{"description":"The method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodDetail"},"example":{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","name":"List public holidays","description":"Lists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types.","returns":"date, weekday, English and local names, regions, type, nationwide flag","platform":{"name":"Nager.Date","domain":"nager.at"},"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."}}},"effect":"read","auth":{"required":false},"cost":{"credits":1},"version":2,"latest_version":2,"revision":1,"pinned_version":null,"status":"ready","versions":[{"version":2,"revision":1,"latest":true,"status":"ready","created_at":"2026-10-22T16:02:41.000Z","changes":"Adds output holidays[].regions."},{"version":1,"revision":2,"status":"ready","created_at":"2026-10-21T09:12:05.000Z","revised_at":"2026-10-24T03:10:19.000Z","changes":""}],"visibility":"public","output_schema":{"type":"object","properties":{"country_name":{"type":"string"},"year":{"type":"integer"},"holidays":{"type":"array","items":{"type":"object"}}}},"example":{"input":{"country":"Germany","year":2027},"output":{"country_name":"Germany","year":2027,"holidays":[{"date":"2027-01-01","weekday":"Friday","english_name":"New Year's Day","local_name":"Neujahr","nationwide":"yes","regions":[],"type":"Public"}]}},"stats":{"success_rate":1,"runs":12,"last_success_at":"2026-10-23T08:24:36.410Z"},"owned":false}}}},"404":{"description":"No such method, or no such version of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No version 9 of date.nager.at/list_public_holidays. Its versions are 1–2.","next_step":"Name one of them (date.nager.at/list_public_holidays@N), or none for the version your organization uses.","param":"method","latest_version":2,"doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"patch":{"operationId":"updateMethod","tags":["Methods"],"summary":"Update a method","description":"{\"pinned_version\": N} switches your organization to version N of any method it sees: runs and queries use it from then on. {\"visibility\": \"public\"} publishes your organization’s method: anyone may then find, run and improve it; a public method stays public. Owners and admins.","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"The site of the method’s slug.","example":"date.nager.at"},{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"The name of the method’s slug.","example":"list_public_holidays"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"Switch version","type":"object","required":["pinned_version"],"additionalProperties":false,"properties":{"pinned_version":{"type":"integer","minimum":1,"description":"The version your organization switches to."}}},{"title":"Publish","type":"object","required":["visibility"],"additionalProperties":false,"properties":{"visibility":{"type":"string","enum":["public"],"description":"\"public\" publishes the method. There is no way back: others may come to rely on it."}}}]},"example":{"pinned_version":1}}}},"responses":{"200":{"description":"The method, as your organization now sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodDetail"},"example":{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","name":"List public holidays","description":"Lists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types.","returns":"date, weekday, English and local names, regions, type, nationwide flag","platform":{"name":"Nager.Date","domain":"nager.at"},"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."}}},"effect":"read","auth":{"required":false},"cost":{"credits":1},"version":1,"latest_version":2,"revision":2,"pinned_version":1,"status":"ready","versions":[{"version":2,"revision":1,"latest":true,"status":"ready","created_at":"2026-10-22T16:02:41.000Z","changes":"Adds output holidays[].regions."},{"version":1,"revision":2,"status":"ready","created_at":"2026-10-21T09:12:05.000Z","revised_at":"2026-10-24T03:10:19.000Z","changes":"","pinned":true}],"visibility":"public","output_schema":{"type":"object","properties":{"country_name":{"type":"string"},"year":{"type":"integer"},"holidays":{"type":"array","items":{"type":"object"}}}},"example":{"input":{"country":"Germany","year":2027},"output":{"country_name":"Germany","year":2027,"holidays":[{"date":"2027-01-01","weekday":"Friday","english_name":"New Year's Day","local_name":"Neujahr","nationwide":"yes","regions":[],"type":"Public"}]}},"stats":{"success_rate":1,"runs":12,"last_success_at":"2026-10-23T08:24:36.410Z"},"owned":false,"latest_changes":"Adds output holidays[].regions."}}}},"400":{"description":"Neither {\"pinned_version\": N} nor {\"visibility\": \"public\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Send {\"pinned_version\": N} to switch your organization to version N, or {\"visibility\": \"public\"} to publish.","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"403":{"description":"Only owners and admins change methods and builds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"Only an owner or admin can change methods.","doc_url":"https://docs.fous.com/guides/errors#forbidden","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"No such method, or no such version of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No version 9 of date.nager.at/list_public_holidays. Its versions are 1–2.","next_step":"Name one of them (date.nager.at/list_public_holidays@N), or none for the version your organization uses.","param":"method","latest_version":2,"doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"Publishing: not your organization’s method (reason not_owned), or another public method has its name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","reason":"not_owned","message":"date.nager.at/list_public_holidays is not your organization's own method. Start a method of your own from it with POST /v1/builds and \"method\": \"date.nager.at/list_public_holidays\".","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"delete":{"operationId":"deleteMethod","tags":["Methods"],"summary":"Delete a method","description":"Deletes your organization’s private method: it no longer runs, and its versions stay for the record. A public method stays, since others may run it. Owners and admins.","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"description":"The site of the method’s slug.","example":"crates.io"},{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"The name of the method’s slug.","example":"search_crates"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}},"example":{"id":"mth_01m5kz9a1b2c3d4e5f6g7h8j9k","deleted":true}}}},"403":{"description":"Only owners and admins change methods and builds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"Only an owner or admin can change methods.","doc_url":"https://docs.fous.com/guides/errors#forbidden","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"No such method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No method \"date.nager.at/list_holidays\". Did you mean \"date.nager.at/list_public_holidays\"?","next_step":"Search with GET /v1/search?query=date%20nager%20at%20list%20holidays, or build one with POST /v1/builds.","param":"method","did_you_mean":"date.nager.at/list_public_holidays","suggestions":[{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","name":"List public holidays","summary":"Lists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types."}],"doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"A public method, or not your organization’s (reason not_owned)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"date.nager.at/list_public_holidays is public and stays, since others may run it. Only a private method can be deleted.","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/methods/{id}":{"get":{"operationId":"getMethodById","tags":["Methods"],"summary":"Get a method by id","description":"A method’s full contract at the version your organization uses (or @N for one version): input and output schema, an example, auth, cost, how it stands (status, repair), its versions and what the latest changes. With wait, the answer is held while the version is under repair; with seen (the status:revision:deletes_at of the last read) while nothing about it has changed. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The method’s id (mth_…).","example":"mth_01m5kzhyjqfwba4j53e676knrq"},{"name":"wait","in":"query","description":"Seconds to hold the answer while the version is under repair (or, with seen, while nothing has changed), 0 to 60.","schema":{"type":"integer","minimum":0,"maximum":60,"default":0}},{"name":"seen","in":"query","schema":{"type":"string"},"description":"What was last read, as <status>:<revision>:<deletes_at or ->; with wait, the answer is held until it differs.","example":"repairing:2:-"}],"responses":{"200":{"description":"The method.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodDetail"},"example":{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","name":"List public holidays","description":"Lists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types.","returns":"date, weekday, English and local names, regions, type, nationwide flag","platform":{"name":"Nager.Date","domain":"nager.at"},"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."}}},"effect":"read","auth":{"required":false},"cost":{"credits":1},"version":2,"latest_version":2,"revision":1,"pinned_version":null,"status":"ready","versions":[{"version":2,"revision":1,"latest":true,"status":"ready","created_at":"2026-10-22T16:02:41.000Z","changes":"Adds output holidays[].regions."},{"version":1,"revision":2,"status":"ready","created_at":"2026-10-21T09:12:05.000Z","revised_at":"2026-10-24T03:10:19.000Z","changes":""}],"visibility":"public","output_schema":{"type":"object","properties":{"country_name":{"type":"string"},"year":{"type":"integer"},"holidays":{"type":"array","items":{"type":"object"}}}},"example":{"input":{"country":"Germany","year":2027},"output":{"country_name":"Germany","year":2027,"holidays":[{"date":"2027-01-01","weekday":"Friday","english_name":"New Year's Day","local_name":"Neujahr","nationwide":"yes","regions":[],"type":"Public"}]}},"stats":{"success_rate":1,"runs":12,"last_success_at":"2026-10-23T08:24:36.410Z"},"owned":false}}}},"404":{"description":"No such method, or no such version of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No version 9 of date.nager.at/list_public_holidays. Its versions are 1–2.","next_step":"Name one of them (date.nager.at/list_public_holidays@N), or none for the version your organization uses.","param":"method","latest_version":2,"doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"patch":{"operationId":"updateMethodById","tags":["Methods"],"summary":"Update a method by id","description":"{\"pinned_version\": N} switches your organization to version N of any method it sees: runs and queries use it from then on. {\"visibility\": \"public\"} publishes your organization’s method: anyone may then find, run and improve it; a public method stays public. Owners and admins.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The method’s id (mth_…).","example":"mth_01m5kzhyjqfwba4j53e676knrq"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"title":"Switch version","type":"object","required":["pinned_version"],"additionalProperties":false,"properties":{"pinned_version":{"type":"integer","minimum":1,"description":"The version your organization switches to."}}},{"title":"Publish","type":"object","required":["visibility"],"additionalProperties":false,"properties":{"visibility":{"type":"string","enum":["public"],"description":"\"public\" publishes the method. There is no way back: others may come to rely on it."}}}]},"example":{"pinned_version":1}}}},"responses":{"200":{"description":"The method, as your organization now sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MethodDetail"},"example":{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","name":"List public holidays","description":"Lists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types.","returns":"date, weekday, English and local names, regions, type, nationwide flag","platform":{"name":"Nager.Date","domain":"nager.at"},"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."}}},"effect":"read","auth":{"required":false},"cost":{"credits":1},"version":1,"latest_version":2,"revision":2,"pinned_version":1,"status":"ready","versions":[{"version":2,"revision":1,"latest":true,"status":"ready","created_at":"2026-10-22T16:02:41.000Z","changes":"Adds output holidays[].regions."},{"version":1,"revision":2,"status":"ready","created_at":"2026-10-21T09:12:05.000Z","revised_at":"2026-10-24T03:10:19.000Z","changes":"","pinned":true}],"visibility":"public","output_schema":{"type":"object","properties":{"country_name":{"type":"string"},"year":{"type":"integer"},"holidays":{"type":"array","items":{"type":"object"}}}},"example":{"input":{"country":"Germany","year":2027},"output":{"country_name":"Germany","year":2027,"holidays":[{"date":"2027-01-01","weekday":"Friday","english_name":"New Year's Day","local_name":"Neujahr","nationwide":"yes","regions":[],"type":"Public"}]}},"stats":{"success_rate":1,"runs":12,"last_success_at":"2026-10-23T08:24:36.410Z"},"owned":false,"latest_changes":"Adds output holidays[].regions."}}}},"400":{"description":"Neither {\"pinned_version\": N} nor {\"visibility\": \"public\"}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Send {\"pinned_version\": N} to switch your organization to version N, or {\"visibility\": \"public\"} to publish.","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"403":{"description":"Only owners and admins change methods and builds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"Only an owner or admin can change methods.","doc_url":"https://docs.fous.com/guides/errors#forbidden","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"No such method, or no such version of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No version 9 of date.nager.at/list_public_holidays. Its versions are 1–2.","next_step":"Name one of them (date.nager.at/list_public_holidays@N), or none for the version your organization uses.","param":"method","latest_version":2,"doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"Publishing: not your organization’s method (reason not_owned), or another public method has its name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","reason":"not_owned","message":"date.nager.at/list_public_holidays is not your organization's own method. Start a method of your own from it with POST /v1/builds and \"method\": \"date.nager.at/list_public_holidays\".","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"delete":{"operationId":"deleteMethodById","tags":["Methods"],"summary":"Delete a method by id","description":"Deletes your organization’s private method: it no longer runs, and its versions stay for the record. A public method stays, since others may run it. Owners and admins.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The method’s id (mth_…).","example":"mth_01m5kz9a1b2c3d4e5f6g7h8j9k"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}},"example":{"id":"mth_01m5kz9a1b2c3d4e5f6g7h8j9k","deleted":true}}}},"403":{"description":"Only owners and admins change methods and builds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"Only an owner or admin can change methods.","doc_url":"https://docs.fous.com/guides/errors#forbidden","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"No such method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No method \"date.nager.at/list_holidays\". Did you mean \"date.nager.at/list_public_holidays\"?","next_step":"Search with GET /v1/search?query=date%20nager%20at%20list%20holidays, or build one with POST /v1/builds.","param":"method","did_you_mean":"date.nager.at/list_public_holidays","suggestions":[{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","name":"List public holidays","summary":"Lists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types."}],"doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"A public method, or not your organization’s (reason not_owned)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"date.nager.at/list_public_holidays is public and stays, since others may run it. Only a private method can be deleted.","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/runs":{"post":{"operationId":"createRun","tags":["Runs"],"summary":"Run a method or a query","description":"Two ways to run. With method (manual): runs that method with inputs that fit its input_schema (1 credit). With query (auto): Fous finds read methods, fills their inputs, runs up to three and returns the data, shaped by output_schema when you send one; when no method fits, it answers from the live web (source \"live\", sources named). A query costs 5 credits, nothing when it has no answer (404 not_found with run_id); status is partial when not all of what was asked was found; one the request check turns away answers 422 request_refused. Both wait up to wait seconds (default 30). A run still going then answers 202 with status \"running\" and goes on: read it with GET /v1/runs/{id}, or stop it with POST /v1/runs/{id}/cancel (nothing is charged). A query ends within 3 minutes. Hanging up before any answer stops a query; after a 202 it goes on.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"method":{"type":"string","minLength":3,"maxLength":200,"description":"The method’s id (mth_…) or slug (<domain>/<name>); add @N to run version N instead of the one your organization uses (its first run sets it)."},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Fits the method’s input_schema; an input sent as null counts as not sent."},"connection":{"type":"string","pattern":"^conn_[0-9a-z]{26}$","description":"A conn_ id, when the method needs an account and you want one other than the default."},"include_raw":{"type":"boolean","description":"Also return the site’s own response as raw."},"wait":{"type":"integer","minimum":0,"maximum":60,"description":"Seconds to wait for the answer, 0 to 60 (default 30); a longer run answers 202 and goes on."}},"required":["method"],"additionalProperties":false},{"type":"object","properties":{"query":{"type":"string","minLength":3,"maxLength":2000,"description":"The data you want, in plain words."},"output_schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"A JSON Schema object (type object) for the answer’s shape."},"platform":{"type":"string","minLength":3,"maxLength":253,"description":"Limit it to one site."},"wait":{"type":"integer","minimum":0,"maximum":60,"description":"Seconds to wait for the answer, 0 to 60 (default 30); a longer query answers 202 and goes on."}},"required":["query"],"additionalProperties":false}]},"examples":{"run":{"summary":"Run a method","value":{"method":"date.nager.at/list_public_holidays","input":{"country":"DE","year":2027}}},"query":{"summary":"Send a query","value":{"query":"Which public holidays does Germany have in 2027?"}}}}}},"responses":{"200":{"description":"Completed (data may be empty: true when the site has nothing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"example":{"id":"run_01m5m0ere4fzdte37jhhn33ycd","status":"completed","method":{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","version":2,"latest_version":2},"data":{"country_name":"Germany","year":2027,"holidays":[{"date":"2027-01-01","weekday":"Friday","english_name":"New Year's Day","local_name":"Neujahr","nationwide":"yes","regions":[],"type":"Public"},{"date":"2027-01-06","weekday":"Wednesday","english_name":"Epiphany","local_name":"Heilige Drei Könige","nationwide":"no","regions":["Baden-Württemberg","Bavaria","Saxony-Anhalt"],"type":"Public"}]},"truncated":false,"cost":{"credits":1},"duration_ms":1751}}}},"202":{"description":"Still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"example":{"id":"run_01m5m0ere4fzdte37jhhn33ycd","status":"running","method":{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","version":2,"latest_version":2},"created_at":"2026-10-23T09:11:15.035Z"}}}},"400":{"description":"Both or neither of method and query, a body that does not fit, or an output_schema that is not an object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Send either method (with its input) or query, not both.","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"402":{"description":"Not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_credits","message":"This run costs 1 credit, and your organization has 0.","next_step":"Add credits at https://app.fous.com/billing. Nothing was charged.","required_credits":1,"available_credits":0,"billing_url":"https://app.fous.com/billing","doc_url":"https://docs.fous.com/guides/errors#insufficient_credits","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"403":{"description":"The method needs a connected account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"connection_required","message":"This method needs a signed-in notion.so account; your login (conn_01m5k2v8c4n6p8r0t2w4y6a8c0) was signed out and needs to sign in again.","next_step":"Sign in at connect_url (a Fous Studio page), or with POST /v1/connections/conn_01m5k2v8c4n6p8r0t2w4y6a8c0/sign-in, then run again. Nothing was charged.","connect":{"platform":"notion.so","type":"session","connection_id":"conn_01m5k2v8c4n6p8r0t2w4y6a8c0","status":"needs_attention"},"connect_url":"https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5k2v8c4n6p8r0t2w4y6a8c0","doc_url":"https://docs.fous.com/guides/errors#connection_required","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"No such method or version, or a query that found no answer (with run_id and steps)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No version 9 of date.nager.at/list_public_holidays. Its versions are 1–2.","next_step":"Name one of them (date.nager.at/list_public_holidays@N), or none for the version your organization uses.","param":"method","latest_version":2,"doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"422":{"description":"The input does not fit (invalid_input), or the request check turned a query away (request_refused)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_input","message":"2 inputs don't fit date.nager.at/list_public_holidays: \"contry\" is not one of its inputs (did you mean \"country\"?), and \"year\" must be an integer from 1 to 9999.","next_step":"Send the inputs below and run it again. Nothing was charged.","param":"input.contry","errors":[{"field":"contry","problem":"unknown","message":"Not an input of this method. Did you mean \"country\"?","did_you_mean":"country"},{"field":"year","problem":"type","message":"Must be an integer from 1 to 9999; got \"next\".","expected":"integer"},{"field":"country","problem":"missing","message":"Required."}],"method":"date.nager.at/list_public_holidays","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."}}},"example":{"method":"date.nager.at/list_public_holidays","input":{"country":"Germany","year":2026}},"doc_url":"https://docs.fous.com/guides/errors#invalid_input","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many runs at once for your plan.","next_step":"Retry in 2 seconds. Nothing was charged.","retry_after":2,"limit":{"kind":"concurrent_runs","value":8},"doc_url":"https://docs.fous.com/guides/errors#rate_limited","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"503":{"description":"The site failed, refused the request or did not answer in time (upstream_error, upstream_blocked, upstream_timeout), the version is under repair (method_repairing, with Retry-After), or billing is briefly unavailable (service_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"method_repairing","message":"date.nager.at/list_public_holidays version 2 is under repair, back in about 4 min. Nothing was charged.","next_step":"Try again later, search for another method with GET /v1/search, or send a query: POST /v1/runs with query.","version":2,"latest_version":2,"repair":{"expected_at":"2026-10-23T09:15:00.000Z","back_in_minutes":4},"retryable":true,"retry_after":240,"alternatives":[],"doc_url":"https://docs.fous.com/guides/errors#method_repairing","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/runs/{id}":{"get":{"operationId":"getRun","tags":["Runs"],"summary":"Get a run","description":"Status and result of a run (a method’s or a query’s), kept 24 hours. Free. A failed run answers with its own status and error, which carries run_id (and for a query its steps).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"run_01m5m0ere4fzdte37jhhn33ycd"},{"name":"wait","in":"query","description":"Seconds to hold the answer while it is still running, 0 to 60.","schema":{"type":"integer","minimum":0,"maximum":60,"default":0}}],"responses":{"200":{"description":"Finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"example":{"id":"run_01m5m0ere4fzdte37jhhn33ycd","status":"completed","method":{"id":"mth_01m5kvvywdeac8fxs7nh0sw68w","slug":"date.nager.at/list_public_holidays","version":2,"latest_version":2},"data":{"country_name":"Germany","year":2027,"holidays":[{"date":"2027-01-01","weekday":"Friday","english_name":"New Year's Day","local_name":"Neujahr","nationwide":"yes","regions":[],"type":"Public"},{"date":"2027-01-06","weekday":"Wednesday","english_name":"Epiphany","local_name":"Heilige Drei Könige","nationwide":"no","regions":["Baden-Württemberg","Bavaria","Saxony-Anhalt"],"type":"Public"}]},"truncated":false,"cost":{"credits":1},"duration_ms":1751}}}},"202":{"description":"Still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"},"example":{"id":"run_01m5m0ere4fzdte37jhhn33ycd","status":"running","created_at":"2026-10-23T09:11:15.035Z"}}}},"403":{"description":"The run needed a connected account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"connection_required","message":"Your notion.so account is no longer signed in. The site sent the request to its sign-in page.","next_step":"Sign in at connect_url (a Fous Studio page), or with POST /v1/connections/conn_01m5k2v8c4n6p8r0t2w4y6a8c0/sign-in, then run again. Nothing was charged.","connect":{"platform":"notion.so","type":"session","connection_id":"conn_01m5k2v8c4n6p8r0t2w4y6a8c0"},"connect_url":"https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5k2v8c4n6p8r0t2w4y6a8c0","run_id":"run_01m5m0ere4fzdte37jhhn33ycd","doc_url":"https://docs.fous.com/guides/errors#connection_required","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"Unknown or expired, or a query that found no answer (with its run_id)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such run.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"The run was stopped (reason stopped)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","reason":"stopped","message":"The run was stopped. Nothing was charged.","run_id":"run_01m5m0ere4fzdte37jhhn33ycd","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"422":{"description":"The site refused the input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_input","message":"The site refused the input: Unknown country \"Atlantis\".","next_step":"Fix the input as the message says, then run it again. Nothing was charged.","retryable":false,"run_id":"run_01m5m0ere4fzdte37jhhn33ycd","doc_url":"https://docs.fous.com/guides/errors#invalid_input","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"503":{"description":"The site failed, refused the request or did not answer in time (upstream_error, upstream_blocked, upstream_timeout), or the method is broken (method_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"upstream_error","message":"The site answered with an error.","next_step":"Try again in a minute, or use another method that gets the same data. Nothing was charged.","retryable":true,"run_id":"run_01m5m0ere4fzdte37jhhn33ycd","doc_url":"https://docs.fous.com/guides/errors#upstream_error","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/runs/{id}/cancel":{"post":{"operationId":"cancelRun","tags":["Runs"],"summary":"Cancel a run","description":"Cancels a run (a method’s or a query’s) that is still going: nothing is charged, reading it afterwards answers 409 conflict with reason \"stopped\", and what the site answers after that is dropped. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"run_01m5m0ere4fzdte37jhhn33ycd"}],"responses":{"200":{"description":"Stopped.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"stopped":{"type":"boolean"}}},"example":{"id":"run_01m5m0ere4fzdte37jhhn33ycd","stopped":true}}}},"404":{"description":"Unknown or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such run.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"Already ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"The run has already ended.","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/builds":{"post":{"operationId":"createBuild","tags":["Builds"],"summary":"Build a method","description":"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.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":5,"maxLength":2000,"description":"What the method should read or do, in plain words."},"platform":{"type":"string","minLength":3,"maxLength":253,"description":"The website (a domain); without it the builder picks the sources."},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"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":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The inputs you want the method to take, as a JSON Schema object."},"output_schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"The fields you want back, as a JSON Schema object."},"method":{"type":"string","minLength":3,"maxLength":200,"description":"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":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"media_type":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/gif"]},"data":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9+/]+=*$"}},"required":["media_type","data"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["url"],"additionalProperties":false}]},"description":"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":{"type":"string","enum":["public","private"],"description":"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."},"connections":{"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"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."}},"required":["query"],"additionalProperties":false},"example":{"query":"Search Rust crates by keyword","platform":"crates.io","visibility":"public"}}}},"responses":{"200":{"description":"The same request already waits for a connected account (requires_auth); it goes on by itself once there is one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"},"example":{"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"}}}},"202":{"description":"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}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"},"example":{"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"}}}},"400":{"description":"Invalid body or schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"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"}}}}},"402":{"description":"Allowance used and not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_credits","message":"Your free builds this month are used up (20 of 20); a build costs 100 credits, and your organization has 12.","next_step":"Add credits at https://app.fous.com/billing. Nothing was charged.","required_credits":100,"available_credits":12,"billing_url":"https://app.fous.com/billing","free_builds":{"used":20,"allowance":20,"resets_at":"2026-11-01T00:00:00.000Z"},"doc_url":"https://docs.fous.com/guides/errors#insufficient_credits","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"403":{"description":"Only owners and admins build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"Only an owner or admin can start builds.","doc_url":"https://docs.fous.com/guides/errors#forbidden","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"No method to start from, or no such version of it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No method \"crates.io/search\" to start from. Did you mean \"crates.io/search_crates\"?","next_step":"Search with GET /v1/search?query=crates%20io%20search, or build one with POST /v1/builds.","param":"method","did_you_mean":"crates.io/search_crates","suggestions":[],"doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"413":{"description":"The body is over 4 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Request body too large.","reason":"body_too_large","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"422":{"description":"No website, app, account or API is involved (not_buildable), or the request check turned it away (request_refused, with its verdict as reason)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_buildable","message":"Writing a poem involves no website, app, account or API.","next_step":"Name the website or the data to get, and send it again.","example":"Get the 7-day forecast for a city from theweathernetwork.com","doc_url":"https://docs.fous.com/guides/errors#not_buildable","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"429":{"description":"Too many requests for the plan this minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many requests for your plan this minute.","next_step":"Retry in 12 seconds.","retry_after":12,"limit":{"kind":"requests_per_minute","value":60},"doc_url":"https://docs.fous.com/guides/errors#rate_limited","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"503":{"description":"The builder or billing is briefly unavailable; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"service_unavailable","message":"The builder is briefly unavailable. Nothing was started or charged.","next_step":"Try again in 30 seconds.","retry_after":30,"doc_url":"https://docs.fous.com/guides/errors#service_unavailable","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"get":{"operationId":"listBuilds","tags":["Builds"],"summary":"List builds","description":"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.","responses":{"200":{"description":"The builds.","content":{"application/json":{"schema":{"type":"object","required":["builds"],"properties":{"builds":{"type":"array","items":{"$ref":"#/components/schemas/Build"}}}},"example":{"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"}]}}}}}}},"/v1/builds/{id}":{"get":{"operationId":"getBuild","tags":["Builds"],"summary":"Get a build","description":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bld_01m5kz8x0vb6dp3jq2w4e5r6t7"},{"name":"wait","in":"query","description":"Seconds to hold the answer while it is still running, 0 to 60.","schema":{"type":"integer","minimum":0,"maximum":60,"default":0}},{"name":"after","in":"query","description":"The number of events you have: a wait ends as soon as there are more.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"},"example":{"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"}}}},"202":{"description":"Still building.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"},"example":{"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"}}}},"404":{"description":"No such build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such build.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"delete":{"operationId":"deleteBuild","tags":["Builds"],"summary":"Dismiss a build","description":"Takes a finished build off the list; the method it made stays. A build waiting for a connected account ends. Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bld_01m5kz8x0vb6dp3jq2w4e5r6t7"}],"responses":{"200":{"description":"Dismissed.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"dismissed":{"type":"boolean"}}},"example":{"id":"bld_01m5kz8x0vb6dp3jq2w4e5r6t7","dismissed":true}}}},"404":{"description":"No such build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such build.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"Still building","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"Only a finished build can be dismissed.","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/builds/{id}/cancel":{"post":{"operationId":"cancelBuild","tags":["Builds"],"summary":"Cancel a build","description":"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.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bld_01m5kz8x0vb6dp3jq2w4e5r6t7"}],"responses":{"200":{"description":"Stopped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"}}}},"404":{"description":"No such build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such build.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"Already ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","message":"The build has already ended.","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/builds/{id}/messages":{"post":{"operationId":"messageBuild","tags":["Builds"],"summary":"Message a build","description":"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).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bld_01m5kz8x0vb6dp3jq2w4e5r6t7"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":2000,"description":"Your message, in plain words."},"images":{"maxItems":4,"type":"array","items":{"anyOf":[{"type":"object","properties":{"media_type":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/gif"]},"data":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9+/]+=*$"}},"required":["media_type","data"],"additionalProperties":false},{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"}},"required":["url"],"additionalProperties":false}]},"description":"Up to 4 pictures that go with it, 2.5 MB in all: each {\"url\"} (a public https address) or {\"media_type\", \"data\"} (base64)."}},"required":["text"],"additionalProperties":false},"example":{"text":"Also return each crate’s license."}}}},"responses":{"200":{"description":"The next build of the thread waits for a connected account (requires_auth).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"}}}},"202":{"description":"The running build takes it at its next step, or the next build of the thread started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Build"},"example":{"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}]}}}},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"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"}}}}},"402":{"description":"Allowance used and not enough credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"insufficient_credits","message":"Your free builds this month are used up (20 of 20); a build costs 100 credits, and your organization has 12.","next_step":"Add credits at https://app.fous.com/billing. Nothing was charged.","required_credits":100,"available_credits":12,"billing_url":"https://app.fous.com/billing","free_builds":{"used":20,"allowance":20,"resets_at":"2026-11-01T00:00:00.000Z"},"doc_url":"https://docs.fous.com/guides/errors#insufficient_credits","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"403":{"description":"Only owners and admins change builds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"Only an owner or admin can change builds.","doc_url":"https://docs.fous.com/guides/errors#forbidden","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"No such build","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such build.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"413":{"description":"The body is over 4 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Request body too large.","reason":"body_too_large","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"422":{"description":"No website, app, account or API is involved (not_buildable), or the request check turned it away (request_refused, with its verdict as reason)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_buildable","message":"Writing a poem involves no website, app, account or API.","next_step":"Name the website or the data to get, and send it again.","example":"Get the 7-day forecast for a city from theweathernetwork.com","doc_url":"https://docs.fous.com/guides/errors#not_buildable","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"429":{"description":"Too many requests for the plan this minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many requests for your plan this minute.","next_step":"Retry in 12 seconds.","retry_after":12,"limit":{"kind":"requests_per_minute","value":60},"doc_url":"https://docs.fous.com/guides/errors#rate_limited","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"503":{"description":"The builder or billing is briefly unavailable; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"service_unavailable","message":"The builder is briefly unavailable. Nothing was started or charged.","next_step":"Try again in 30 seconds.","retry_after":30,"doc_url":"https://docs.fous.com/guides/errors#service_unavailable","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/builds/{id}/images/{position}":{"get":{"operationId":"getBuildImage","tags":["Builds"],"summary":"Get a build image","description":"An image sent with a build request or a message, by its position (the url in images names it). Free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"bld_01m5kz8x0vb6dp3jq2w4e5r6t7"},{"name":"position","in":"path","required":true,"schema":{"type":"integer","minimum":0},"example":0}],"responses":{"200":{"description":"The image.","content":{"image/*":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"No such image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such image.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/connections":{"post":{"operationId":"createConnection","tags":["Connections"],"summary":"Connect an account","description":"type \"session\": a website login, signed in inside Fous one step at a time. The answer carries the sign-in’s first step (sign_in, after up to wait seconds): the fields the site asks for, which you answer with POST /v1/connections/{id}/sign-in using the person’s details, or the person signs in at connect_url, a Fous Studio page. Once signed in, the connection turns active and becomes the site’s default. An organization has one login per site: asking again answers 200 with that connection, and its sign-in when one runs (an active login stays as it is; to sign in another account, restart the sign-in on it). type \"api_key\": the site’s own API key, stored encrypted and never returned. The same key sent again for the same site answers 200 with the connection already there (made the site’s default) instead of adding another.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","type","attest"],"additionalProperties":false,"properties":{"platform":{"type":"string","description":"The site’s domain."},"type":{"type":"string","enum":["session","api_key"]},"api_key":{"type":"string","description":"type api_key only."},"login_url":{"type":"string","description":"type session only: the site’s sign-in page (https, on the site), when it is not the obvious one."},"attest":{"type":"boolean","enum":[true],"description":"Your confirmation that you are authorized to use this account for this purpose. Kept on the connection with who confirmed it and when."},"wait":{"type":"integer","minimum":0,"maximum":60,"default":30,"description":"type session: seconds to wait for the sign-in’s first step."}}},"example":{"platform":"notion.so","type":"session","attest":true}}}},"responses":{"200":{"description":"The site’s connection already there: its login (with its sign-in when one runs), or that API key saved before.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"example":{"id":"conn_01m5kyvsdxea78rpr2j3qzzd1z","platform":{"name":"Notion","domain":"notion.so"},"type":"session","created_at":"2026-10-23T08:43:26.528Z","status":"active","default":true,"account_hint":"p…@example.com","checked_at":"2026-10-23T08:44:10.000Z","message":"This organization already has a connected notion.so account (p…@example.com); runs use it. To use another account, sign in again on this connection (it replaces it) or remove it in Studio."}}}},"201":{"description":"Created; a login’s sign-in is under way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"example":{"id":"conn_01m5kyvsdxea78rpr2j3qzzd1z","platform":{"name":"Notion","domain":"notion.so"},"type":"session","created_at":"2026-10-23T08:43:26.528Z","status":"pending","default":false,"account_hint":null,"connect_url":"https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5kyvsdxea78rpr2j3qzzd1z","checked_at":null,"sign_in":{"status":"input","step_id":"stp_7h2k9q","message":"Enter your email to continue.","fields":[{"id":"fld_1","label":"Email address","type":"email","required":true}],"choices":[],"expires_at":"2026-10-23T08:53:41.000Z"}}}}},"400":{"description":"Invalid body, or no attest: true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Connecting an account needs your confirmation that you are authorized to use it: send attest: true.","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"429":{"description":"Too many requests for the plan this minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many requests for your plan this minute.","next_step":"Retry in 12 seconds.","retry_after":12,"limit":{"kind":"requests_per_minute","value":60},"doc_url":"https://docs.fous.com/guides/errors#rate_limited","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"503":{"description":"No browser is free for a sign-in now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"service_unavailable","message":"Sign-in isn't available right now. Try again shortly.","doc_url":"https://docs.fous.com/guides/errors#service_unavailable","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"get":{"operationId":"listConnections","tags":["Connections"],"summary":"List connections","description":"Your organization’s connections, with any sign-in that runs. Free.","responses":{"200":{"description":"The organization’s connections.","content":{"application/json":{"schema":{"type":"object","required":["connections"],"properties":{"connections":{"type":"array","items":{"$ref":"#/components/schemas/Connection"}}}},"example":{"connections":[{"id":"conn_01m5kyvsdxea78rpr2j3qzzd1z","platform":{"name":"Notion","domain":"notion.so"},"type":"session","created_at":"2026-10-23T08:43:26.528Z","status":"active","default":true,"account_hint":"p…@example.com","checked_at":"2026-10-23T08:44:10.000Z"}]}}}}}}},"/v1/connections/{id}":{"get":{"operationId":"getConnection","tags":["Connections"],"summary":"Check a connection","description":"The connection and its sign-in, if one runs. With wait, the answer is held while the sign-in works or waits for the person’s approval, until it moves on.","parameters":[{"name":"id","in":"path","required":true,"description":"conn_ followed by 26 characters.","schema":{"type":"string"}},{"name":"wait","in":"query","description":"Seconds to hold the answer while the sign-in works or waits for an approval, 0 to 60.","schema":{"type":"integer","minimum":0,"maximum":60,"default":0}}],"responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"example":{"id":"conn_01m5kyvsdxea78rpr2j3qzzd1z","platform":{"name":"Notion","domain":"notion.so"},"type":"session","created_at":"2026-10-23T08:43:26.528Z","status":"active","default":true,"account_hint":"p…@example.com","checked_at":"2026-10-23T08:44:10.000Z"}}}},"400":{"description":"wait is not 0 to 60","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"wait must be a whole number of seconds, 0 to 60.","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"Unknown connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such connection.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"patch":{"operationId":"updateConnection","tags":["Connections"],"summary":"Update a connection","description":"Makes the connection its site’s default: the account runs and builds on that site use when a call names none (a working connection still comes before a default that does not work).","parameters":[{"name":"id","in":"path","required":true,"description":"conn_ followed by 26 characters.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["default"],"additionalProperties":false,"properties":{"default":{"type":"boolean","enum":[true]}}},"example":{"default":true}}}},"responses":{"200":{"description":"The connection, now the default.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"example":{"id":"conn_01m5kyvsdxea78rpr2j3qzzd1z","platform":{"name":"Notion","domain":"notion.so"},"type":"session","created_at":"2026-10-23T08:43:26.528Z","status":"active","default":true,"account_hint":"p…@example.com","checked_at":"2026-10-23T08:44:10.000Z"}}}},"404":{"description":"Unknown connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such connection.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"delete":{"operationId":"deleteConnection","tags":["Connections"],"summary":"Delete a connection","description":"Removes the connection and wipes its saved key or sign-in. Only a person signed in to Fous Studio removes a connection: an API key gets 403.","parameters":[{"name":"id","in":"path","required":true,"description":"conn_ followed by 26 characters.","schema":{"type":"string"}}],"responses":{"200":{"description":"Disconnected.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean"}}},"example":{"id":"conn_01m5kyvsdxea78rpr2j3qzzd1z","deleted":true}}}},"403":{"description":"Only Studio removes connections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"forbidden","message":"Remove connections in Fous Studio.","doc_url":"https://docs.fous.com/guides/errors#forbidden","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"Unknown connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such connection.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/connections/{id}/sign-in":{"post":{"operationId":"signIn","tags":["Connections"],"summary":"Run a sign-in","description":"A website login’s sign-in, run inside Fous. {\"attest\": true} starts one (or answers with the one that runs); add \"restart\": true to start again in its place, for instance to sign in another account; login_url names the sign-in page. {\"step_id\", \"fields\"} answers the current step with the person’s details, by field id; {\"step_id\", \"choice\"} picks one of its choices. {} answers with the sign-in as it is. Each call waits up to wait seconds while the sign-in works, then answers with the connection and its next step (sign_in), until it is active. Values are used once to sign in and never returned; Fous keeps them sealed only to sign the account in again by itself when the site signs it out. Starting a sign-in counts against the plan’s requests per minute.","parameters":[{"name":"id","in":"path","required":true,"description":"conn_ followed by 26 characters.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"attest":{"type":"boolean","enum":[true],"description":"To start or restart: your confirmation that you are authorized to use this account."},"restart":{"type":"boolean","description":"With attest: start again in place of the sign-in that runs."},"login_url":{"type":"string","description":"With attest: the site’s sign-in page (https, on the site)."},"step_id":{"type":"string","description":"The step you answer (sign_in.step_id)."},"fields":{"type":"object","additionalProperties":{"type":["string","boolean"]},"description":"With step_id: a value for each of the step’s field ids (required ones filled in)."},"choice":{"type":"string","description":"With step_id: the id of one of the step’s choices."},"wait":{"type":"integer","minimum":0,"maximum":60,"default":30,"description":"Seconds to wait for the next step."}}},"example":{"step_id":"stp_7h2k9q","fields":{"fld_1":"person@example.com"}}}}},"responses":{"200":{"description":"The connection and its next step; active, without sign_in, once signed in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"example":{"id":"conn_01m5kyvsdxea78rpr2j3qzzd1z","platform":{"name":"Notion","domain":"notion.so"},"type":"session","created_at":"2026-10-23T08:43:26.528Z","status":"pending","default":false,"account_hint":null,"connect_url":"https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5kyvsdxea78rpr2j3qzzd1z","checked_at":null,"sign_in":{"status":"input","step_id":"stp_4n8w2c","message":"Enter your password to continue.","fields":[{"id":"fld_2","label":"Password","type":"password","required":true}],"choices":[],"expires_at":"2026-10-23T08:54:02.000Z"}}}}},"400":{"description":"Invalid answer, an API key, or no attest: true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Answer with exactly the step’s field ids (required ones filled in), or with one of its choices.","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"No such connection, or no sign-in runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No sign-in is running for this connection. Start one with attest: true.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"409":{"description":"Still working on the last answer, or not the current step","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"conflict","reason":"step_expired","message":"That step is no longer the current one. Answer the current step.","doc_url":"https://docs.fous.com/guides/errors#conflict","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"429":{"description":"Too many requests for the plan this minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Too many requests for your plan this minute.","next_step":"Retry in 12 seconds.","retry_after":12,"limit":{"kind":"requests_per_minute","value":60},"doc_url":"https://docs.fous.com/guides/errors#rate_limited","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"503":{"description":"No browser is free for a sign-in now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"service_unavailable","message":"Sign-in isn't available right now. Try again shortly.","doc_url":"https://docs.fous.com/guides/errors#service_unavailable","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}},"delete":{"operationId":"cancelSignIn","tags":["Connections"],"summary":"Cancel the sign-in","description":"Stops the sign-in that runs (none: nothing to stop). The connection keeps its status.","parameters":[{"name":"id","in":"path","required":true,"description":"conn_ followed by 26 characters.","schema":{"type":"string"}}],"responses":{"200":{"description":"The connection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"},"example":{"id":"conn_01m5kyvsdxea78rpr2j3qzzd1z","platform":{"name":"Notion","domain":"notion.so"},"type":"session","created_at":"2026-10-23T08:43:26.528Z","status":"pending","default":false,"account_hint":null,"connect_url":"https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5kyvsdxea78rpr2j3qzzd1z","checked_at":null}}}},"400":{"description":"An API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_request","message":"Only a website login (type session) signs in; this connection is an API key.","doc_url":"https://docs.fous.com/guides/errors#invalid_request","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}},"404":{"description":"Unknown connection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No such connection.","doc_url":"https://docs.fous.com/guides/errors#not_found","request_id":"req_mh7c2k9xQ1v3Zt8LbN0pRwY4"}}}}}}}},"/v1/account":{"get":{"operationId":"getAccount","tags":["Account"],"summary":"Get the account","description":"The organization behind the key: credit balance, plan limits, monthly build allowance and prices. Free.","responses":{"200":{"description":"The account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"},"example":{"organization":{"id":"org_01M4CD7TVHDBPFQHZD05XMW5PB","name":"Agent Test"},"credits":{"balance":585,"balance_usd":5.85},"limits":{"requests_per_minute":60,"concurrent_runs":8,"monthly_spend_limit_credits":null},"builds":{"free_per_month":20,"used_this_month":9},"prices":{"search":0,"run":1,"query":5,"build_after_allowance":100,"private_build":100},"key":{"kind":"user","name":"Server","client_name":null,"expires_at":null,"last_used_at":"2026-10-23T09:11:15.000Z"}}}}}}}}},"x-error-codes":[{"code":"invalid_request","status":400,"retryable":false,"description":"The request itself is malformed: a missing or invalid parameter or body field, or (413, reason body_too_large) a body over 4 MB. Fix it and send again."},{"code":"unauthorized","status":401,"retryable":false,"description":"No API key, or the key is invalid, revoked or expired; reason says which. Send Authorization: Bearer <key>."},{"code":"insufficient_credits","status":402,"retryable":false,"description":"Not enough credits: required_credits is what the run, query or build costs and available_credits what you have; a build also shows free_builds, and a private one private: true. reason spend_limit (with spend_limit) means the monthly spend limit is reached. billing_url says where to add credits. Nothing was charged."},{"code":"forbidden","status":403,"retryable":false,"description":"Not allowed for this credential: removing a connection with an API key (people remove them in Fous Studio), or for Studio’s session not a member of the organization, a role that may only read (owners and admins build, run, connect and change methods), or a failed CSRF check."},{"code":"insufficient_scope","status":403,"retryable":false,"description":"The key lacks the scope this call needs; the message names it."},{"code":"connection_required","status":403,"retryable":false,"description":"The method runs with an account on its site and none is connected, or it signed out. connect names the platform and type (and connection_id and its status when you have a connection there); connect_url is the Fous Studio page where a person connects it. Sign in there or with POST /v1/connections/{id}/sign-in, or connect one with POST /v1/connections, then run again."},{"code":"not_found","status":404,"retryable":false,"description":"No such method, run, build or connection. For a method, did_you_mean names the one most likely meant and suggestions lists close matches."},{"code":"request_timeout","status":408,"retryable":true,"description":"The answer took longer than the server waits. A run may still finish: run with a shorter wait and poll GET /v1/runs/{id}."},{"code":"conflict","status":409,"retryable":false,"description":"Not possible in the state it is in: a method that is not your organization’s (reason not_owned), deleting a public method, publishing under a slug another public method has, a run that was stopped (reason stopped; a write that was already sent carries may_have_run), cancelling a run or build that already ended, dismissing a build that is still running, or a sign-in answer while it still works on the last one (reason sign_in_busy) or for a step that is no longer the current one (reason step_expired)."},{"code":"invalid_input","status":422,"retryable":false,"description":"The input does not fit the method’s input_schema. errors lists every problem at once (unknown names with did_you_mean, missing, wrong types, values outside an enum or range); input_schema is the method’s own and example a call that fits. Nothing was charged."},{"code":"request_refused","status":422,"retryable":false,"description":"The request check turned a build or a query away; reason is its verdict: unclear or (a query) unsupported, with an example of a request it takes, or explicit, harmful, platform_probe or refused, with doc_url the acceptable use policy. Nothing started or was charged."},{"code":"not_buildable","status":422,"retryable":false,"description":"A build request that involves no website, app, account or API, so no method can do it; example shows a request that can be built. Nothing started or was charged."},{"code":"rate_limited","status":429,"retryable":true,"description":"Too many requests, searches or runs at once for your plan: limit says which (and its value), retry_after and the Retry-After header when to retry. A site limiting Fous is upstream_error with reason site_rate_limited."},{"code":"server_error","status":500,"retryable":true,"description":"Something failed inside Fous. Try again shortly."},{"code":"upstream_error","status":503,"retryable":true,"description":"The site answered with an error, or its answer no longer fits the method (Fous checks the method on its saved examples and repairs it when they break too). reason site_rate_limited means the site itself slowed you down."},{"code":"upstream_blocked","status":503,"retryable":true,"description":"The site refused the request on every route Fous tried."},{"code":"upstream_timeout","status":503,"retryable":true,"description":"The site did not answer in time, or no browser was free in time."},{"code":"method_unavailable","status":503,"retryable":false,"description":"The method’s spec itself failed (Fous checks it on its saved examples and repairs it when they fail too). Search for another method or send a query."},{"code":"method_repairing","status":503,"retryable":true,"description":"The version is under repair, confirmed broken: runs are refused until the repair ends, usually within minutes. repair says when it is back at the latest (also Retry-After), version and latest_version which version this is, alternatives which methods do the same. Nothing was charged."},{"code":"service_unavailable","status":503,"retryable":true,"description":"Fous itself (the builder, billing, queries) is briefly unavailable; nothing was started or charged. Retry after retry_after seconds."}],"x-mcp":{"url":"https://api.fous.com/mcp","tools":["search","run","run_action","query","get_run","stop","build","connect","connections","methods","builds","account"]}}