> ## 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.

# 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.

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

## Install

```bash theme={null}
npm install asteroid-odyssey
```

Or with pnpm:

```bash theme={null}
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](/integrate/call-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:

```ts theme={null}
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:

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

## Common Functions

The most frequently used functions are listed below. See the [API reference](/api-reference/overview) for the full set.

| Function | Purpose |
| - | - |
| `contextGet` | Fetch your user context, including organization IDs |
| `workflowList` | List workflows with pagination |
| `workflowCreate` | Create a workflow with its first version |
| `workflowByIdUpdate` | Rename a workflow (name must be 1-100 characters) |
| `workflowByIdDelete` | Delete a workflow and its versions |
| `workflowExecutePost` | 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 login profiles (filter with `organizationId`) |
| `agentProfilesCreate` | Create a login profile |
| `agentProfileGet` | Fetch a single profile |
| `agentProfileUpdate` | Update a profile |
| `agentProfileDelete` | Delete a profile |
| `vaultItemsList` | List secrets (filter with `organizationId`) |
| `vaultItemsCreate` | Create a secret |
| `vaultItemGet` | Fetch a secret (values omitted) |
| `workflowVersionsExecute` | Execute a specific workflow version |
| `workflowHeadGetFiles` | Read the editable head as a [directory of files](/integrate/version-in-git) |
| `workflowVersionsGetFiles` | Read a published version as a directory of files |
| `workflowHeadPatchFiles` | Write files back to the editable head |
| `workflowHeadPublish` | Publish the editable head as the workflow's next version |

## Common Patterns

<CardGroup cols={2}>
  <Card title="Execute and poll" icon="play" href="/integrate/call-a-workflow" horizontal>
    The full run loop, including the statuses that wait for a person
  </Card>

  <Card title="Every execute field" icon="sliders" href="/integrate/call-a-workflow" horizontal>
    Inputs, profiles, files, metadata, and version pinning
  </Card>

  <Card title="Files" icon="file" href="/concepts/filesystem" horizontal>
    Stage files before an execution and download what the workflow produced
  </Card>

  <Card title="Profiles" icon="id-card" href="/concepts/profiles" horizontal>
    Secrets, Email Inbox, and profile groups
  </Card>
</CardGroup>

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

```ts theme={null}
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

<CardGroup cols={2}>
  <Card title="Python SDK" icon="terminal" href="/sdks/python">
    See the Python SDK guide
  </Card>

  <Card title="API" icon="book" href="/api-reference/overview">
    Browse the API landing page and common workflows
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.