Tips & Best Practices

A few patterns that make integrations more reliable and easier to maintain.

Write specific prompts

The starterPrompt is the single biggest factor in agent performance. Vague instructions produce vague results.

Be explicit about what you want created. "Analyze the data" is a starting point. "Analyze the sales sheet, calculate revenue by region, and create a summary document with a chart" gives the agent a clear finish line.

Include constraints. If you need a specific output format, say so. If certain sheets or artifacts in the template matter, reference them by name.

Use successPrompt and failurePrompt to close the loop. These are how you wire the agent back to your system. A successPrompt like "POST the project URL to https://your-app.com/webhook" turns an autonomous session into an event your backend can act on.

Design templates for reuse

Templates define everything the agent starts with — sheets, documents, instructions, and context. A well-structured template makes every API call more predictable.

• Pre-configure sheet schemas with the field types your workflow needs. The agent works faster when it doesn't have to guess your data structure.
• Add project instructions (the README) with standing context the agent should always know — business rules, naming conventions, output expectations.
• Keep templates focused. One template per use case. A template that tries to handle both "quarterly reporting" and "ad hoc analysis" handles neither well.

Handle errors consistently

Every endpoint returns standard HTTP status codes. Build your error handling around them:

• 401 — Authentication failed. Check that your API key is active and the Authorization header uses the Bearer prefix.
• 404 — The resource wasn't found or your key doesn't have access. The API returns 404 for both to prevent ID enumeration.
• 409 — A race condition, usually when a thread already has an active execution. Retry after a short delay.
• 500 — Something went wrong on our end. Retry with backoff.

A simple retry with exponential backoff (starting at 1 second, capping at 30 seconds) handles most transient failures.

Common mistakes

Hardcoding template IDs. Template IDs can change if a template is deleted and recreated. Use the List Templates endpoint to discover IDs at runtime, or build a lookup by name.

Ignoring the workspace scope. API keys are scoped to a single workspace. A key can't access templates or projects from a different workspace — even if the user who created the key belongs to both.

Skipping successPrompt and failurePrompt. Without these, you have no way to know when the agent finishes or gets stuck. Always include at least a successPrompt with a webhook callback for production integrations.

Sending empty or minimal prompts. The agent runs autonomously. It can't ask you clarifying questions. Front-load the specificity.

Related resources

• API Overview — endpoints, base URL, and how the pieces fit together.
• Authentication — generate and manage API keys.
• Create Project from Template — full endpoint reference.
• Create Thread in Project — run additional work on existing projects.