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 | projects.create | A project you can reuse |
| Give the agent a task | runs.create | An accepted run ID |
| Get the finished work | runs.wait, then workspaces.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.
Optional integration paths
The core API exposes reusable projects, 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
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.