TypeScript SDK

Installation

npm install asteroid-odyssey typescript ts-node

Create your TypeScript file (run_agent.ts)

import { 
  AsteroidClient, 
  executeAgent,
  waitForExecutionResult 
} from 'asteroid-odyssey';

// Create client and execute agent
const client = AsteroidClient('YOUR_API_KEY');

const executionId = await executeAgent(client, 'YOUR_AGENT_ID', {
  dynamic_data: {
    DATA: "First name: John, Last name: Smith"
  },
  agent_profile_id: 'YOUR_AGENT_PROFILE_ID'
});

// Wait for result
const result = await waitForExecutionResult(client, executionId);
console.log(result);

Run the agent

Replace your API key, your agent_id, and update the dynamic_data with your agent’s variables (or remove if no variables), then run:

npx ts-node run_agent.ts

Agent Creation: Agents can only be created through the Asteroid Platform web interface. The API is designed for executing existing agents, not creating them.

Method Reference

Method	Purpose	Returns
`executeAgent()`	Start agent execution	`execution_id`
`waitForExecutionResult()`	Wait for completion	`result`
`getExecutionStatus()`	Check current status	`status_info`
`getExecutionResult()`	Get final result	`result`
`uploadExecutionFiles()`	Upload files	`upload_response`
`getExecutionFiles()`	Get execution files	`files[]`
`downloadExecutionFile()`	Download file	`file_path`
`getBrowserSessionRecording()`	Get recording URL	`url`
`getCredentialsPublicKey()`	Get encryption public key	`public_key`
`getAgentProfiles()`	List agent profiles	`profiles`
`getAgentProfile()`	Get specific profile	`profile`
`createAgentProfile()`	Create new profile	`profile`
`updateAgentProfile()`	Update existing profile	`profile`
`deleteAgentProfile()`	Delete profile	`success_message`
`getLastNExecutionActivities()`	Get execution activities	`activities`
`addMessageToExecution()`	Add message to execution	`void`

TypeScript Examples

Comprehensive examples including error handling, advanced patterns, and real-world workflows

API Reference

Complete API documentation with all available endpoints

Core Methods

executeAgent() - Execute an agent with prompt variables

Execute an agent with the provided parameters.Parameters:

client: The configured API client
agentId: The ID of the agent to execute
executionData: The execution parameters
agent_profile_id: Optional ID of the agent profile

Returns: The execution IDRaises:

Error: If the execution request fails

const executionId = await executeAgent(client, 'YOUR_AGENT_ID', {
  dynamic_data: {
    DATA: "First name: John, Last name: Smith"
  },
  agent_profile_id: 'YOUR_AGENT_PROFILE_ID'
});

getExecutionStatus() - Get the current status for an execution

Get the current status for an execution.Parameters:

client: The configured API client
executionId: The execution identifier

Returns: The execution status detailsRaises:

Error: If the status request fails

const status = await getExecutionStatus(client, executionId);
console.log(status.status);

getExecutionResult() - Get the final result of an execution

Get the final result of an execution.Parameters:

client: The configured API client
executionId: The execution identifier

Returns: The result object of the executionRaises:

Error: If the result request fails or execution failed

const result = await getExecutionResult(client, executionId);
console.log(result);

waitForExecutionResult() - Wait for an execution to reach a terminal state and return the result

Wait for an execution to reach a terminal state and return the result. Continuously polls the execution status until it’s either “completed”, “cancelled”, or “failed”.Parameters:

client: The configured API client
executionId: The execution identifier
interval: Polling interval in milliseconds (default is 1000)
timeout: Maximum wait time in milliseconds (default is 3600000 - 1 hour)

Returns: The execution result if completedRaises:

Error: If the execution ends as “cancelled” or “failed”, or times out

const result = await waitForExecutionResult(client, executionId, 2000);

AsteroidClient() - Create an API client with authentication

Create an API client with authentication.Parameters:

apiKey: Your API key for authentication

Returns: A configured API clientRaises:

Error: If the client initialization fails

const client = AsteroidClient('YOUR_API_KEY');

uploadExecutionFiles() - Upload files to an execution

Upload files to an execution.Parameters:

client: The configured API client
executionId: The execution identifier
files: Array of files to upload (Blob or File objects)

Returns: The uploaded file IDs and success messageRaises:

Error: If the upload request fails

import { readFileSync } from 'fs';

const pdfFile = new File([readFileSync('document.pdf')], 'document.pdf', { type: 'application/pdf' });
const files = [pdfFile];
const result = await uploadExecutionFiles(client, executionId, files);
console.log(result.file_ids);

getExecutionFiles() - Get a list of files associated with an execution

Get a list of files associated with an execution.Parameters:

client: The configured API client
executionId: The execution identifier

Returns: A list of files associated with the executionRaises:

Error: If the files request fails

const files = await getExecutionFiles(client, 'execution_123');
files.forEach(file => {
  console.log(`File: ${file.fileName}, Size: ${file.fileSize}`);
});

downloadExecutionFile() - Download a file from an execution using its signed URL

Download a file from an execution using its signed URL.Parameters:

client: The configured API client
file: The File object containing the signed URL and metadata
downloadPath: Path where the file should be saved. Can be a directory or full file path
createDirs: Whether to create parent directories if they don’t exist (default: true)
timeout: Request timeout in seconds (default: 30)

Returns: The full path where the file was savedRaises:

Error: If the download request fails

const files = await getExecutionFiles(client, 'execution_123');
for (const file of files) {
  // Download to specific directory
  const savedPath = await downloadExecutionFile(client, file, './downloads/');
  console.log(`Downloaded ${file.fileName} to ${savedPath}`);
}

getBrowserSessionRecording() - Get the browser session recording URL for a completed execution

Get the browser session recording URL for a completed execution.Parameters:

client: The configured API client
executionId: The execution identifier

Returns: The browser session recording URLRaises:

Error: If the recording request fails

const recording = await getBrowserSessionRecording(client, executionId);
console.log(recording.recording_url);

Agent Profiles

getAgentProfiles() - Get a list of agent profiles

Get agent profiles for an organization (or all organizations for the user if not specified).Parameters:

client: The configured API client
organizationId: The organization identifier (optional). Returns all agent profiles if no organizationId is provided.

Returns: A list of agent profilesRaises:

Error: If the agent profiles request fails

const profiles = await getAgentProfiles(client, 'org-123');

getAgentProfile() - Get a specific agent profile by ID

Get a specific agent profile by ID.Parameters:

client: The configured API client
profileId: The agent profile ID

Returns: The agent profileRaises:

Error: If the agent profile request fails

const profile = await getAgentProfile(client, 'profile_123');

createAgentProfile() - Create a new agent profile

Create a new agent profile.Parameters:

client: The configured API client
payload: The agent profile data

Returns: The created agent profileRaises:

Error: If the agent profile creation fails

const profile = await createAgentProfile(client, {
  name: 'My Profile',
  description: 'Profile description',
  organization_id: 'org_123',
  proxy_cc: 'us',
  proxy_type: 'residential',
  captcha_solver_active: false,
  sticky_ip: false,
  credentials: [],
  cookies: [
    {
      // Display name for the cookie in UI
      name: 'Session Cookie',
      // The actual cookie key and value
      key: 'session_id',
      value: 'abc123',
      // Required domain scope for the cookie
      domain: '.example.com',
      // Security attributes
      secure: true,
      http_only: true,
      same_site: 'Lax', // 'Strict' | 'Lax' | 'None'
      // Optional expiry in ISO 8601
      expiry: '2026-01-01T00:00:00Z',
      // Required created_at in ISO 8601
      created_at: new Date().toISOString()
    }
  ]
});

updateAgentProfile() - Update an existing agent profile

Update an existing agent profile.Parameters:

client: The configured API client
profileId: The agent profile ID
payload: The update data

Returns: The updated agent profileRaises:

Error: If the agent profile update fails

// Add and remove cookies in the same request
const updated = await updateAgentProfile(client, 'profile_123', {
  name: 'New Name',
  cookies_to_add: [
    {
      name: 'Auth Token',
      key: 'auth_token',
      value: 'new-token-value',
      domain: '.example.com',
      secure: true,
      http_only: true,
      same_site: 'Strict'
    }
  ],
  cookies_to_delete: ['cookie_id_to_remove']
});

// Cookie object shape
type Cookie = {
  id?: string;           // Only present on existing cookies
  name: string;          // Display name
  key: string;           // Cookie name
  value: string;         // Cookie value
  domain: string;        // e.g. '.example.com'
  secure: boolean;       // Send over HTTPS only
  http_only: boolean;    // Not accessible to JS
  same_site: 'Strict' | 'Lax' | 'None';
  expiry?: string;       // ISO 8601 (optional)
  created_at: string;    // ISO 8601
};

deleteAgentProfile() - Delete an agent profile by ID

Delete an agent profile by ID.Parameters:

client: The configured API client
profileId: The agent profile ID

Returns: A success messageRaises:

Error: If the agent profile deletion fails

await deleteAgentProfile(client, 'profile_123');

Get Started

Fundamentals

SDKs

Changelog

Support & Security

Method Reference

TypeScript Examples

API Reference

Core Methods

Agent Profiles

Get Started

Fundamentals

SDKs

Changelog

Support & Security

​Method Reference

TypeScript Examples

API Reference

​Core Methods

​Agent Profiles

Method Reference

Core Methods

Agent Profiles