Use Public APIs for Sparkforge Agent Studio

Public APIs for Agent Studio let your software call, manage, and run any Sparkforge agent without logging into the dashboard. Requests are scoped to a sub-account (location) and authenticated with OAuth 2.0 or a Private Integration Token (PIT).

What You Can Build

• Embed AI agents inside mobile apps, SaaS products, voice assistants, or internal tools.
• Trigger agent workflows from Zapier, Make, Airflow, or any external automation.
• Centralize security with OAuth 2.0 scoped tokens.
• Use PIT integrations for server-to-server calls inside your own environment.
• Parse rich JSON output without extra NLP work.

Endpoints

List Agents

GET /agent-studio/public-api/agents

• Required: locationId
• Optional: limit, offset
• Returns every active agent for the location — useful for populating a dropdown.

Get Agent

GET /agent-studio/public-api/agents/{agentId}

• Required: locationId
• Returns name, status, tool nodes, variables, and lifecycle stage.

Execute Agent

POST /agent-studio/public-api/agents/{agentId}/execute

• Body: { locationId, input, executionId? }
• First call omits executionId. The response returns one so subsequent calls continue the same conversation.

Authentication

OAuth 2.0 bearer tokens or PIT values both ride in the Authorization header:

Authorization: Bearer {access_token}

Generate a Private Integration under Settings > Developer, scope it to a sub-account, and you can skip the full OAuth flow for internal apps.

Setup Steps

1. Enable AI Agents > Agent Studio in your sub-account and confirm at least one agent is in Production.
2. Open Settings > Developer and create a Private Integration or OAuth App.
3. Copy the Client ID + Client Secret (OAuth) or PIT value.
4. For OAuth, exchange the code at POST /oauth/token with grant_type=authorization_code. Store the access token and refresh as needed.
5. Test with the List Agents endpoint:

curl -H "Authorization: Bearer {token}" \
  "https://services.sparkforgehq.com/agent-studio/public-api/agents?locationId={locationId}"

1. Save the agentId values you want to run.
2. Execute an agent:

curl -X POST \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "locationId":"abc123", "input":{ "prompt":"Write a Facebook ad for plumbers"} }' \
  https://services.sparkforgehq.com/agent-studio/public-api/agents/{agentId}/execute

Store the returned executionId if you need multi-turn conversations.