Documentation Index
Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
Use this file to discover all available pages before exploring further.
Use the asteroid-odyssey TypeScript SDK to execute agents, 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
pnpm add asteroid-odyssey
Quickstart
import { client, agentExecutePost, executionGet } from 'asteroid-odyssey';
client.setConfig({
headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});
const { data, error } = await agentExecutePost({
path: { agentId: 'your-agent-id' },
body: {
inputs: {
customerName: 'Jane Doe',
},
metadata: {
source: 'docs',
},
},
});
if (error) throw new Error(JSON.stringify(error));
const executionId = data.executionId;
// Poll until complete
let exec;
do {
await new Promise((r) => setTimeout(r, 3000));
const res = await executionGet({ path: { executionId } });
exec = res.data;
} while (exec?.status === 'running' || exec?.status === 'starting');
console.log(exec?.status, exec?.inputs);
Client Configuration
All SDK functions share the singleton client. Configure it once at startup:
import { client } from 'asteroid-odyssey';
client.setConfig({
headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
// Optional: override the base URL
baseUrl: 'https://odyssey.asteroid.ai/agents/v2',
});
client override if you need per-request auth:
const { data } = await executionGet({
client: myOtherClient,
path: { executionId },
});
Exported Functions
| Function | Purpose |
|---|
agentList | List agents with pagination |
agentExecutePost | Execute an agent |
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 (requires 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 |
Common Patterns
Executions
Files
Profiles
import {
client,
agentExecutePost,
executionsList,
executionActivitiesGet,
executionUserMessagesAdd,
} from 'asteroid-odyssey';
client.setConfig({
headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});
const { data } = await agentExecutePost({
path: { agentId: 'your-agent-id' },
body: {
inputs: {
task: 'Summarize the attached invoice',
},
},
});
const executionId = data!.executionId;
const { data: page } = await executionsList({
query: {
page: 1,
pageSize: 10,
executionId,
},
});
const { data: activities } = await executionActivitiesGet({
path: { executionId },
query: { limit: 20, order: 'desc' },
});
await executionUserMessagesAdd({
path: { executionId },
body: { message: 'Please use the latest file only.' },
});
console.log(page?.items);
console.log(activities?.map((a) => a.payload.activityType));
import {
client,
agentExecutePost,
tempFilesStage,
executionContextFilesUpload,
executionContextFilesGet,
} from 'asteroid-odyssey';
import { readFileSync, writeFileSync } from 'node:fs';
client.setConfig({
headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});
const fileBuffer = readFileSync('./invoice.pdf');
const invoice = new File([fileBuffer], 'invoice.pdf', { type: 'application/pdf' });
const { data: staged } = await tempFilesStage({
path: { organizationId: 'your-org-id' },
body: { files: [invoice] },
});
const { data } = await agentExecutePost({
path: { agentId: 'your-agent-id' },
body: {
inputs: { task: 'Read the staged file' },
tempFiles: staged?.tempFiles,
},
});
const executionId = data!.executionId;
await executionContextFilesUpload({
path: { executionId },
body: { files: [invoice] },
});
const { data: files } = await executionContextFilesGet({
path: { executionId },
});
for (const file of files ?? []) {
const response = await fetch(file.downloadUrl, {
headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});
if (!response.ok) throw new Error(`Download failed: ${response.status}`);
writeFileSync(`./downloads/${file.fileName}`, Buffer.from(await response.arrayBuffer()));
}
import {
client,
agentProfilesList,
agentProfilesCreate,
agentProfileUpdate,
} from 'asteroid-odyssey';
client.setConfig({
headers: { 'X-Asteroid-Agents-Api-Key': process.env.ASTEROID_API_KEY! },
});
const { data: profiles } = await agentProfilesList({
query: { organizationId: 'your-org-id', page: 1, pageSize: 20 },
});
console.log(profiles?.items?.map((p) => `${p.id}: ${p.name}`));
const { data: created } = await agentProfilesCreate({
body: {
name: 'Shared Billing Profile',
description: 'Reusable browser profile for billing workflows',
organizationId: 'your-org-id',
proxyCountryCode: 'us',
proxyType: 'residential',
captchaSolverActive: false,
stickyIp: false,
credentials: [],
cookies: [],
},
});
await agentProfileUpdate({
path: { profileId: created!.id },
body: { description: 'Updated description' },
});
- Use
inputs for execution variables — dynamicData is deprecated.
executionActivitiesGet returns Array<AgentsExecutionActivity> directly, not a wrapped object.agentProfilesList requires organizationId in the query.- 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-Asteroid-Agents-Api-Key header.
Python SDK
See the Python SDK guide
API
Browse the API landing page and common workflows
