Social Media API, MCP and CLI Documentation

You are reading the Staging 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

Environment	Base URL
Staging	`https://api-staging.octospark.ai`

SDKs default to production. Pass baseUrl to target a different Octospark API environment.

Authentication

Create an API key in Octospark from Organization settings - API Keys. Use it as a bearer token:

curl "https://api-staging.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-staging.octospark.ai/v1/organizations?limit=1" \
    -H "Authorization: Bearer $OCTOSPARK_TOKEN" |
    jq -r '.data[0].id'
)"

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

curl "https://api-staging.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.organizations.listOrganizations({
  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.teams.listTeams({
  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.social.listPosts({
  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

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

​Base URL

​Authentication

​First API flow

​TypeScript

​Python

​Errors

Base URL

Authentication

First API flow

TypeScript

Python

Errors