API Quickstart

Get started with the Asteroid API and SDKs

Use this page as the starting point for programmatic access to Asteroid.

1. Sign up for Asteroid

   Follow the instructions here to sign up for the Asteroid platform: Asteroid signup using your Google account.

2. Get your API key

   Once you have signed up, you can retrieve your API key from the API keys page.

   
3. Set your environment variable

   Our examples use ASTEROID_API_KEY as a convenient environment variable. Set it once and read it from your own code:

     export ASTEROID_API_KEY="your-key-here"
   
4. Choose how you want to integrate

   Pick the starting point that matches your workflow:

   • TypeScript SDK for the high-level helper client and generated namespaces
   • Python SDK for the high-level client and generated subpackages
   • API for the main API landing page and common workflows

   The reference pages in this section are the best place to inspect individual request and response schemas.

5. Run your first execution

   Use one of the SDK guides above, or start from the minimal examples below.

   TypeScript

   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' },
     },
   });
   if (error) throw new Error(JSON.stringify(error));
   const executionId = data.executionId;
   
   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);
   

   import os
   import time
   from asteroid_odyssey import Configuration, ApiClient
   from asteroid_odyssey.api.agents_api import AgentsApi
   from asteroid_odyssey.api.execution_api import ExecutionApi
   from asteroid_odyssey.models.agents_agent_execute_agent_request import AgentsAgentExecuteAgentRequest
   
   config = Configuration(api_key={"ApiKeyAuth": os.environ["ASTEROID_API_KEY"]})
   
   with ApiClient(config) as api_client:
       agents_api = AgentsApi(api_client)
       exec_api = ExecutionApi(api_client)
   
       response = agents_api.agent_execute_post(
           agent_id="your-agent-id",
           agents_agent_execute_agent_request=AgentsAgentExecuteAgentRequest(
               inputs={"customerName": "Jane Doe"},
           ),
       )
       execution_id = response.execution_id
   
       while True:
           time.sleep(3)
           execution = exec_api.execution_get(execution_id=execution_id)
           if execution.status not in ("running", "starting"):
               break
   
       print(execution.status)
   

Next Steps

Once you’ve set up your environment, you can:

1. Inspect the endpoint reference pages in this API section for request and response details
2. Follow the TypeScript SDK or Python SDK guides for end-to-end examples
3. Review Agent Profiles if you need persistent browser state, credentials, or proxies

Need help? Contact us at [e-mail]