Conversation AI Public API in Sparkforge

By Sparkforge Support Team ·Last reviewed May 3, 2026

The Conversation AI API gives developers programmatic control over Sparkforge AI agents, actions, and message generations. Authenticate with a Personal Integration Token or JWT and use sub-account scopes to provision agents, manage actions, and pull conversation data.

The Conversation AI API exposes the same capabilities you have in the Conversation AI UI: create and manage agents, attach actions, and retrieve message-level generation data. Use it to provision agents at scale, automate action updates, and pull data into your own analytics or compliance systems.

What you can do with the API

  • Provision agents for new sub-accounts in seconds instead of clicking through the UI.
  • Apply consistent agent settings and actions across many locations via scripts or CI/CD.
  • Pull generations (AI response details) into dashboards, QA workflows, and audit logs.
  • Trigger external workflows and log events outside Sparkforge.
  • Scope tokens to read-only or write so each integration only gets what it needs.

Authentication: PIT vs JWT

Personal Integration Tokens (PIT) are fast to generate and scope for server-to-server work. JSON Web Tokens (JWT) are for OAuth-based app flows. Either method works for Conversation AI endpoints.

Generate a Personal Integration Token

  1. Open Settings → Private Integrations in the Sparkforge sub-account that owns the agent.
  2. Add a name and description.
  3. Select the Conversation AI scopes you need (read-only vs write).
  4. Create the token and copy it immediately.
  5. Store it in your secrets manager and reference it from there.

Use a sub-account token, not an agency token, so calls run inside the right location context.

Endpoint families

Agents

  • Create an Agent
  • Search Agents
  • Get Agent
  • Update Agent
  • Delete Agent

Actions

  • Attach Action To Agent
  • List Actions For An Agent
  • Get Action By ID
  • Update Action
  • Remove Action From Agent
  • Update Followup Settings

Generations

  • Get Generation Details (message-level response data)

Common 403 cause

If your token looks valid but you keep getting 403s, the token is almost always missing the required scope or it is an agency token instead of a sub-account token. Regenerate it with the right scope at the location level.

Frequently Asked Questions

Should I use a sub-account or agency token?
Use a sub-account token so API calls execute in the correct location context. Agency tokens will return 403 on most Conversation AI endpoints.
Can I mix PIT and JWT auth?
Yes. PIT is best for simple server-to-server scripts. JWT is built for OAuth app flows. Both authenticate against the same endpoints.
Where do I find the agentId?
Create an agent or call the Search Agents endpoint, then use the returned id field for downstream calls to actions, generations, and updates.
How do I audit AI responses programmatically?
Hit the Generations endpoint to retrieve message-level prompt, response, and source data, then store it in your analytics or compliance pipeline.
Why does my valid-looking token return 403?
The token is almost always missing the required scope, or it is an agency token rather than a sub-account token for the target location.

Was this article helpful?

Related Articles