Give an agent a task and get back its response and saved files. The API, SDKs, and CLI work with Macrofold Cloud and self-hosted deployments using the same resource methods.
Start with the API quickstart, or give your coding agent the setup prompt.
Connect once
Create a key in your dashboard's API keys page. Store it in your server environment as MACROFOLD_API_KEY.
SDKs default to https://app.macrofold.ai. For a self-hosted, local, or staging deployment, set the client's base URL to that deployment's origin, without /v1. Use a key created on the same deployment. See Cloud setup or self-hosting.
Three steps
| Step | SDK operation | Result |
|---|---|---|
| Choose a home for the files | workspaces.create | A workspace you can reuse |
| Give the agent a task | runs.create | An accepted run ID |
| Get the finished work | runs.wait, then worktrees.readFile | Response text and persisted file bytes |
Method spelling follows each language's conventions. Use streamText / stream_text when you want text as it arrives, or events for tool activity and structured progress. Choose a language.
One model call without an agent
Use immediate inference for a single model-native LLM request, classification or score. inferences.create returns the finalized result directly; inferences.stream delivers output deltas followed by the same saved result. Both preserve a Run for accounting and recovery, without a workspace file tree, sandbox or worker queue. HTTP 202 is an exceptional recovery receipt, not ordinary queued delivery.
To use your own Hugging Face model or existing chat/SystemOne server, configure a model deployment and supply its deployment_id through the same inference API. SystemOne returns complete decisions and rejects streaming before admission.
Optional integration paths
The core API exposes reusable workspaces, worktrees, presets, sessions, runs and connections. Integration paths package those capabilities for a particular use case without replacing them. Customer agents adds customer ownership resolution, atomic setup and embedded connection consent under /v1/integration-paths/customer-agents. Choose it when each app customer needs an assistant; use the core API directly for a different resource layout. OpenAPI marks these operations with x-platform-layer: integration-path and the customerAgents tag.
Build on it
- Share files between agents or continue a conversation.
- Choose a harness: the Unified Harness Interface keeps run operations consistent across native agents.
- Read saved files and connect GitHub.
- Connect tools and model accounts.
- Start runs from Slack, webhooks, or schedules.
Reference when you need it
Model and agent streaming distinguishes available run streams from direct LLM streaming and unsupported combinations.
Authentication, errors, retries, and pagination · Streaming and webhooks · HTTP quickstart · All SDK methods · OpenAPI
The interactive API reference is available at /reference on your deployment. Keep API keys on your server; authorize your application's users before submitting work on their behalf.
Use the customer MCP to access the same operations from Codex or Claude Code.