TypeScript SDK

Use the Asteroid TypeScript SDK to execute workflows, monitor runs, and manage profiles

Use the asteroid-odyssey TypeScript SDK to execute workflows, monitor executions, work with files, and manage profiles from your application.

The SDK exports a client singleton and individual endpoint functions. Configure the client once with your API key, then call the functions directly.

Install

npm install asteroid-odyssey

Or with pnpm:

pnpm add asteroid-odyssey

Run a workflow

The end-to-end example — execute, poll to a terminal status, read the result — lives on Deploy a workflow. This page covers what is specific to the SDK.

Client Configuration

All SDK functions share the singleton client. Configure it once at startup:

import { client } from 'asteroid-odyssey';

client.setConfig({
  headers: { 'X-Api-Key': process.env.ASTEROID_API_KEY! },
  // Optional: override the base URL
  baseUrl: 'https://odyssey.asteroid.ai/agents/v2',
});

Every function accepts an optional client override if you need per-request auth:

const { data } = await executionGet({
  client: myOtherClient,
  path: { executionId },
});

Common Functions

The most frequently used functions are listed below. See the API reference for the full set.

Function	Purpose
contextGet	Fetch your user context, including organization IDs
agentList	List workflows with pagination
agentCreate	Create a workflow with an initial workflow
agentByIdUpdate	Rename a workflow (name must be 1-100 characters)
agentByIdDelete	Delete a workflow and its workflows
agentExecutePost	Execute a workflow
executionGet	Fetch execution details
executionsList	List executions with filters
executionActivitiesGet	Fetch execution activities (returns Array)
executionStatusUpdate	Update execution status (e.g. cancel)
executionUserMessagesAdd	Send a user message to a running execution
executionContextFilesGet	List files on an execution
executionContextFilesUpload	Upload files to a running execution
tempFilesStage	Stage temporary files before execution
agentProfilesList	List agent profiles (filter with organizationId)
agentProfilesCreate	Create an agent profile
agentProfileGet	Fetch a single profile
agentProfileUpdate	Update a profile
agentProfileDelete	Delete a profile
agentWorkflowsExecute	Execute a specific workflow version
agentWorkflowHeadGetFiles	Read the editable head as a directory of files
agentWorkflowsGetFilesByVersion	Read a published version as a directory of files
agentWorkflowHeadPatchFiles	Write files back to the editable head
agentWorkflowHeadPublishHead	Publish the editable head as the agent’s version

Common Patterns

Execute and poll

The full run loop, including the statuses that wait for a person

Every execute field

Inputs, profiles, files, metadata, and version pinning

Files

Stage files before an execution and download what the workflow produced

Profiles

Credentials, cookies, proxies, and pools

Send a message to a running workflow, and read its timeline:

import { executionActivitiesGet, executionUserMessagesAdd } from 'asteroid-odyssey';

const { data: activities } = await executionActivitiesGet({
  path: { executionId },
  query: { limit: 20, order: 'desc' },
});
console.log(activities?.map((a) => a.payload.activityType));

await executionUserMessagesAdd({
  path: { executionId },
  body: { message: 'Please use the latest file only.' },
});

Notes

• Use inputs for execution variables — dynamicData is deprecated.
• executionActivitiesGet returns Array<AgentsExecutionActivity> directly, not a wrapped object.
• All functions return { data, error }. Check error before using data.
• File list responses include a downloadUrl per file. Fetch it with your API key in the X-Api-Key header.

Related Resources

Python SDK

See the Python SDK guide

API

Browse the API landing page and common workflows