You are reading the documentation. Use the environment link in the top navigation to switch between the production and staging docs sites.
Build against Octospark with the generated SDKs, direct HTTP API, CLI, or MCP surfaces. All developer surfaces use the same public OpenAPI document and the same bearer-token authentication model.

​
Base URL

EnvironmentBase URL
Production
Staging
SDKs default to production. Pass baseUrl when targeting staging or another Octospark API environment.

​
Authentication

Create an API key in Octospark from Organization settings - API Keys. Use it as a bearer token: 
curl "https://api.octospark.ai/v1/organizations?limit=1" \
  -H "Authorization: Bearer $OCTOSPARK_TOKEN"
API keys are stored encrypted at rest, looked up by a SHA-256 hash, and displayed only once when created.

​
First API flow

Start by discovering the organization ID, then discover a team ID, then call a team-scoped operation. 
export OCTOSPARK_ORG_ID="$(
  curl -s "https://api.octospark.ai/v1/organizations?limit=1" \
    -H "Authorization: Bearer $OCTOSPARK_TOKEN" |
    jq -r '.data[0].id'
)"

export OCTOSPARK_TEAM_ID="$(
  curl -s "https://api.octospark.ai/v1/teams?organizationId=$OCTOSPARK_ORG_ID&limit=1" \
    -H "Authorization: Bearer $OCTOSPARK_TOKEN" |
    jq -r '.data[0].id'
)"

curl "https://api.octospark.ai/v1/teams/$OCTOSPARK_TEAM_ID/posts?limit=10" \
  -H "Authorization: Bearer $OCTOSPARK_TOKEN"
The same flow through the CLI: 
octospark orgs list --fields response.data.id,response.data.name
octospark teams list --organization-id "$OCTOSPARK_ORG_ID" --fields response.data.id,response.data.name
octospark posts list --team-id "$OCTOSPARK_TEAM_ID" --fields response.total,response.data

​
TypeScript

import { OctosparkClient } from "@octospark/sdk"

const octospark = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const organizations = await octospark.organizationsListOrganizations({
  query: { limit: 1 }
}) as { data: Array<{ id: string }> }

const organizationId = organizations.data[0]?.id
if (!organizationId) {
  throw new Error("No organization found")
}

const teams = await octospark.teamsListTeams({
  query: { organizationId, limit: 1 }
}) as { data: Array<{ id: string }> }

const teamId = teams.data[0]?.id
if (!teamId) {
  throw new Error("No team found")
}

const posts = await octospark.socialListPosts({
  teamId,
  query: { limit: 10 }
})

​
Python

import os
from octospark_sdk import OctosparkClient

octospark = OctosparkClient(token=os.environ["OCTOSPARK_TOKEN"])
organizations = octospark.organizations_list_organizations(
    query={"limit": 1}
)
organization_id = organizations["data"][0]["id"]

teams = octospark.teams_list_teams(
    query={"organizationId": organization_id, "limit": 1}
)
team_id = teams["data"][0]["id"]

posts = octospark.social_list_posts(
    teamId=team_id,
    query={"limit": 10}
)

​
Errors

StatusMeaning
400Request body, query string, or path parameter is malformed.
401Authorization is missing, invalid, expired, or revoked.
403The token is valid but does not have permission for the resource.
404The endpoint or resource was not found.
409The request conflicts with existing state.
429The client has exceeded a rate limit.
5xxServer error. Retry safe requests with exponential backoff.