Query an API directly or route a prompt

Successful prompt searches cost 5 credits, including prompts with a named API. Direct calls with api, operation, and input cost 1 credit. The full price is reserved before execution; failures without a completed receipt release it. 170-second overall request deadline; individual workflows also enforce their execution limits. With Idempotency-Key, work continues after client disconnection; completed terminal results are retained for 24 hours. Identical retries return the same status/body. Concurrent retries return 409 with Retry-After and Location. A changed request under the same key returns 409. Stale unfinished claims never dispatch again. Without a key, a repeated POST is a new billable request. Switching JSON/SSE transport does not change identity.

Authentication

Send your organization’s secret key as Authorization: Bearer $FOUS_API_KEY. See authentication.

Parameters

Name	Location	Required	Type	Description
`Idempotency-Key`	header	No	string	Unique opaque key per logical query, scoped to the authenticated organization. Retain it for retries.

Request body

A request body is required.

application/json

Schema: QueryRequest.

Provide prompt OR api + operation + input. Allowed and blocked API lists must not overlap. Use include alone, or schema with optional mapping.

Field	Type	Required	Description
`api`	string	No
`operation`	string	No
`version`	integer	No	Pin an immutable method contract version. Omit to keep the method’s established default version; publishing a new version never moves that default. Only valid with api, operation and input.
`input`	__schema0	No
`prompt`	string	No
`allowed_apis`	array	No
`blocked_apis`	array	No
`attachments`	array	No
`stream`	boolean	No
`response`	object	No
`visibility`	"public" · "private"	No	A handle reaches your organization’s private API and the public API alike; a private method wins a name collision. Set public or private to use one side only.

Full schema:

{
  "type": "object",
  "description": "Provide prompt OR api + operation + input. Allowed and blocked API lists must not overlap. Use include alone, or schema with optional mapping.",
  "properties": {
    "api": {
      "type": "string",
      "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$"
    },
    "operation": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{0,99}$"
    },
    "version": {
      "type": "integer",
      "description": "Pin an immutable method contract version. Omit to keep the method’s established default version; publishing a new version never moves that default. Only valid with api, operation and input.",
      "exclusiveMinimum": 0,
      "maximum": 2147483647
    },
    "input": {
      "$ref": "#/components/schemas/QueryRequest/$defs/__schema0"
    },
    "prompt": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000
    },
    "allowed_apis": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$"
      },
      "minItems": 1,
      "maxItems": 100,
      "uniqueItems": true
    },
    "blocked_apis": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^@[a-z0-9][a-z0-9_-]{0,99}$"
      },
      "minItems": 1,
      "maxItems": 100,
      "uniqueItems": true
    },
    "attachments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^file_[0-9a-f]{32}$"
          },
          "purpose": {
            "type": "string",
            "enum": [
              "input",
              "context"
            ],
            "default": "input"
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "maxItems": 4
    },
    "stream": {
      "type": "boolean"
    },
    "response": {
      "type": "object",
      "properties": {
        "format": {
          "type": "string",
          "enum": [
            "json",
            "text",
            "markdown"
          ],
          "default": "json"
        },
        "include": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1000
          },
          "minItems": 1,
          "maxItems": 1000,
          "uniqueItems": true
        },
        "schema": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        "mapping": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "target": {
                "type": "string",
                "maxLength": 1000
              },
              "source": {
                "type": "string",
                "maxLength": 1000
              }
            },
            "required": [
              "target",
              "source"
            ],
            "additionalProperties": false
          },
          "minItems": 1,
          "maxItems": 1000
        }
      },
      "additionalProperties": false,
      "allOf": [
        {
          "not": {
            "anyOf": [
              {
                "required": [
                  "include",
                  "schema"
                ]
              },
              {
                "required": [
                  "include",
                  "mapping"
                ]
              }
            ]
          }
        },
        {
          "if": {
            "required": [
              "mapping"
            ]
          },
          "then": {
            "required": [
              "schema"
            ]
          }
        }
      ]
    },
    "visibility": {
      "type": "string",
      "description": "A handle reaches your organization’s private API and the public API alike; a private method wins a name collision. Set public or private to use one side only.",
      "enum": [
        "public",
        "private"
      ]
    }
  },
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ]
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/QueryRequest/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/components/schemas/QueryRequest/$defs/__schema0"
          }
        }
      ]
    }
  },
  "oneOf": [
    {
      "required": [
        "prompt"
      ],
      "not": {
        "anyOf": [
          {
            "required": [
              "operation"
            ]
          },
          {
            "required": [
              "input"
            ]
          },
          {
            "required": [
              "version"
            ]
          }
        ]
      }
    },
    {
      "required": [
        "api",
        "operation",
        "input"
      ],
      "not": {
        "required": [
          "prompt"
        ]
      }
    }
  ]
}

Example: direct

{
  "api": "@x_com",
  "operation": "tweet_lookup",
  "version": 1,
  "input": {
    "tweet_id": "123"
  },
  "response": {
    "include": [
      "text"
    ]
  }
}

Example: automatic

{
  "prompt": "How many followers does elonmusk have?",
  "api": "@x_com"
}

Responses

200

Completed JSON result, or an SSE stream ending with result/error. SSE HTTP status stays 200; terminal errors carry error.status.

X-Request-Id: string
Idempotency-Replayed: boolean
Location: string
X-Fous-Billing-Status: string

application/json

Schema: QueryResult.

Field	Type	Required	Description
`success`	value	Yes
`data`	object	Yes

Full schema:

{
  "type": "object",
  "properties": {
    "success": {
      "const": true
    },
    "data": {
      "type": "object",
      "properties": {
        "output": {},
        "receipt": {
          "$ref": "#/components/schemas/Receipt"
        }
      },
      "required": [
        "output",
        "receipt"
      ],
      "additionalProperties": true
    }
  },
  "required": [
    "success",
    "data"
  ],
  "additionalProperties": false
}

text/event-stream

Full schema:

{
  "type": "string"
}

"event: progress\ndata: {\"request_id\":\"req_1234567890\",\"stage\":\"accepted\",\"message\":\"Request received.\"}\n\nevent: result\ndata: {\"success\":true,\"data\":{\"output\":{},\"receipt\":{\"request_id\":\"req_1234567890\",\"api\":\"@x_com\",\"operation\":\"tweet_lookup\",\"billing\":{\"status\":\"settled\",\"reserved_credits\":1,\"charged_credits\":1}}}}\n\n"