---
title: "Execute Atom"
method: POST
path: "/api/atoms/execute"
tags: ["atoms"]
---

# Execute Atom

`POST /api/atoms/execute`

## Request

- Base URL: `https://api.tintin-x.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tintin-x.com/api/atoms/execute`
- Auth: HTTP bearer

Execute an atom — dispatches to the worker via SQS, awaits result.

Auth: JWT Bearer token OR X-Internal-Key + X-Internal-User-Id headers.

## Request body

- AtomExecuteRequest: Request body for POST /api/atoms/execute. Extra fields (url, s3_key, etc.) are merged into params so skills can pass atom-specific args at the top level without wrapping in params.
  - `agent_id` string, uuid, required
  - `atom_type` string, required
  - `params` object
  - `conversation_id` string, uuid, nullable
  - `callback_url` string, nullable
  - `wait_timeout` integer, nullable
  - `submit_mode` 'sync' | 'async', nullable
  - `ack_message` string, nullable
  - `next_step` object, nullable
  - `post_process` object, nullable

## Response `200`

Successful Response

- AtomResponse: Unified response for all atoms — sync and async.
  - `status` 'ok' | 'pending' | 'error', required
  - `atom_type` string, required
  - `job_id` string, nullable
  - `result` object, nullable
  - `metadata` object, nullable
  - `storage_path` string, nullable
  - `error` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tintin-x/apis/tintin-api.md) · [All operations](https://skmtc.dev/tintin-x/apis/tintin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tintin-x/apis/tintin-api/revisions/8839a8d0a66c?raw)