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.
- One client, every API:
fi.Client(Python,pip install futureagi) andClientfrom@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/nullis; 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).
Defaults to FI_API_KEY.
Defaults to FI_SECRET_KEY.
Defaults to FI_BASE_URL, then https://api.futureagi.com.
Defaults to FI_WORKSPACE_ID. Sent as X-Workspace-Id.
Per-request timeout: seconds in Python (default 60), milliseconds in TypeScript (default 60000).
Default 2. Retries 429 on every call, and timeouts and 5xx on calls that are safe to repeat.
Sent with every request.
Python only. Reject a response that misses a field the contract marks required (see Strict mode).
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, RateLimitErrorimport { APIError, NotFoundError, RateLimitError } from "@future-agi/sdk/platform"; | Status | Error |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 402 | PaymentRequiredError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | ConflictError |
| 422 | UnprocessableEntityError |
| 429 | RateLimitError |
| 5xx | InternalServerError |
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
Account
client.account: 1 method.
Workspaces
client.workspaces: 2 methods.
Usage
client.usage: 1 method.
Response models
What the account methods return.
Datasets & evals
Datasets
client.datasets: 20 methods.
Evals
client.evals: 15 methods.
Experiments
client.experiments: 3 methods.
Optimizations
client.optimizations: 3 methods.
Response models
What the datasets & evals methods return.
Prompts
Observability
Projects
client.projects: 2 methods.
Traces
client.traces: 4 methods.
Spans
client.spans: 2 methods.
Sessions
client.sessions: 2 methods.
Dashboards
client.dashboards: 13 methods.
Error clusters
client.error_clusters: 2 methods.
Alerts
client.alerts: 2 methods.
Response models
What the observability methods return.
Annotation
Annotation queues
client.annotation_queues: 23 methods.
Annotations
client.annotations: 5 methods.
Scores
client.scores: 3 methods.
Response models
What the annotation methods return.
Simulation
Agents
client.agents: 5 methods.
Simulation
client.simulation: 11 methods.
Response models
What the simulation methods return.
Knowledge bases
Knowledge bases
client.knowledge_bases: 5 methods.
File knowledge bases
client.file_knowledge_bases: 7 methods.
Response models
What the knowledge bases methods return.
Gateway
Questions & Discussion