Platform SDK reference

Every method of the Future AGI platform client in Python and TypeScript: the client, conventions for arguments, pagination, errors and strict mode, and one page per resource.

📝
TL;DR
  • One client, every API: fi.Client (Python, pip install futureagi) and Client from @future-agi/sdk (TypeScript)
  • 162 methods across 25 resources, generated from the API contract; each page lists parameters, return types and the REST endpoint
  • Omitted arguments are not sent, None / null is; list calls return pagers; HTTP errors raise typed exceptions

The platform client is generated from the Future AGI API contract, so every REST operation has one method with the same name in Python and TypeScript. This reference is generated from the same source as the SDKs. For narrative guides, see the SDK overview.

The client

Credentials come from the constructor or from the environment: FI_API_KEY, FI_SECRET_KEY, and optionally FI_BASE_URL and FI_WORKSPACE_ID.

from fi import Client

client = Client()  # or Client(api_key=..., secret_key=..., base_url=...)
for dataset in client.datasets.list():
    print(dataset.name)
import { Client } from "@future-agi/sdk";

const client = new Client(); // or new Client({ apiKey, secretKey, baseUrl })
for await (const dataset of client.datasets.list()) {
  console.log(dataset.name);
}

Python also ships AsyncClient with the same methods, awaited (await client.datasets.get(...), async for over pagers).

api_key / apiKey string Optional

Defaults to FI_API_KEY.

secret_key / secretKey string Optional

Defaults to FI_SECRET_KEY.

base_url / baseUrl string Optional

Defaults to FI_BASE_URL, then https://api.futureagi.com.

workspace_id / workspaceId string Optional

Defaults to FI_WORKSPACE_ID. Sent as X-Workspace-Id.

timeout number Optional

Per-request timeout: seconds in Python (default 60), milliseconds in TypeScript (default 60000).

max_retries / maxRetries integer Optional

Default 2. Retries 429 on every call, and timeouts and 5xx on calls that are safe to repeat.

default_headers / defaultHeaders object Optional

Sent with every request.

strict_responses boolean Optional

Python only. Reject a response that misses a field the contract marks required (see Strict mode).

http_client / fetch object Optional

Python: an httpx.Client (or httpx.AsyncClient) to use instead of the SDK’s own. TypeScript: a replacement for the global fetch.

Conventions

Arguments

Path parameters are positional; every other parameter is a keyword argument in Python and a field of the params object in TypeScript. An argument you leave out is not sent. Passing None (Python) or null (TypeScript) sends null, which clears a nullable field. In Python the omitted-argument sentinel is fi.platform.NOT_GIVEN.

A PATCH is always a partial update: send only the fields you want to change.

Fields the contract does not describe yet go through the escape hatches: extra_query= and extra_body= in Python, options.extraQuery and options.extraBody in TypeScript.

Per-call options

Every method accepts options (fi.platform.RequestOptions / RequestOptions) with headers, timeout and max_retries / maxRetries overrides for that one call.

Pagination

A method marked paginated returns a pager instead of a list and fetches pages as you iterate. Python SyncPager / AsyncPager: iterate, or first_page() for one Page (items, number, raw), or to_list(limit=None). TypeScript Pager: for await, or firstPage(), or toArray(limit?).

Responses

Responses are parsed into models (fi.platform.models / @future-agi/sdk/platform/models), documented on the response-models page of each area below. Parsing is tolerant: a field the backend leaves out is None / undefined, an extra field is kept. The backend’s {status, result} envelope is unwrapped for you.

Strict mode

Client(strict_responses=True) (Python) raises ResponseValidationError when a response misses a field the contract marks required. Use it in tests to catch contract drift; leave it off in production.

Errors

HTTP errors raise a subclass of APIError with status_code / status, body, detail and request_id / requestId. Import the error classes from fi.platform (Python) and from @future-agi/sdk/platform (TypeScript): the package root does not export them, and its RateLimitError is an older, unrelated class that an instanceof check against platform errors never matches.

from fi.platform import APIError, NotFoundError, RateLimitError
import { APIError, NotFoundError, RateLimitError } from "@future-agi/sdk/platform";
StatusError
400BadRequestError
401AuthenticationError
402PaymentRequiredError
403PermissionDeniedError
404NotFoundError
409ConflictError
422UnprocessableEntityError
429RateLimitError
5xxInternalServerError

Network failures raise APIConnectionError. All of them extend FutureAGIError.

Stability

A method marked Beta may change without notice; the first call emits a BetaWarning (Python) or a console warning (TypeScript).

Any endpoint

client.request(method, path, ...) calls any endpoint under the base URL with the client’s authentication, retries and error handling, for operations this reference does not list yet.

Resources

Account

Datasets & evals

Prompts

Observability

Annotation

Simulation

Knowledge bases

Gateway

Was this page helpful?

Questions & Discussion