---
title: "Run one ESM module in Kody's hosted sandbox."
method: POST
path: "/v1/execute"
tags: ["execute"]
---

# Run one ESM module in Kody's hosted sandbox.

`POST /v1/execute`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/execute`
- Auth: HTTP bearer

Run one ESM module in Kody's hosted sandbox. Same inputs and result envelope as the MCP `execute` tool (`content`, `structuredContent`, `isError`). Requires `Authorization: Bearer kody_at_…` with `org:execute`. JSON bodies follow the Open API 5 MiB cap. Older CLIs keep using MCP `execute`; this route does not accept MCP OAuth.

Org permission: `org:execute`.

## Request body

- object
  - `code` string: Single ESM module string with a default export. Imports may be npm packages compatible with the Cloudflare Workers runtime.
  - `invoke` string: Published package export to run (`kody:@owner/name/export`). Omit code when this is set.
  - `params` object: JSON object passed to the default export.
  - `responseLimit` integer
  - `conversationId` string: Optional short conversation identifier. Ties related calls together. If you already have a `conversationId` from an earlier response in the same conversation, pass it back unchanged. Otherwise omit this field to receive a server-generated ID, then reuse the returned `conversationId` on subsequent calls - this enables optimizations like reduced response size. Do not invent your own `conversationId`.
  - `memoryContext` object: Optional short, structured task context for memory retrieval. Keep it brief and factual rather than hidden reasoning. If durable memory may need to be written or deleted, agents should later run `metaMemoryVerify` before mutating memory.
    - `task` string: Optional task or goal summary for future memory retrieval.
    - `query` string: Optional task or goal summary for future memory retrieval.
    - `entities` string[]: Optional short phrases that identify important entities, constraints, or references for future memory retrieval.
    - `constraints` string[]: Optional short phrases that identify important entities, constraints, or references for future memory retrieval.
  - `idempotencyKey` string
  - `credentials` object: Optional credential picks by need key, for `credential(key)` / `credentials(key)` in this run: `{ github: "work", google: ["work", "personal"], x: { name: "work", scope: "org" } }`. A string is a credential name; add `scope` when an org and a personal credential share the name; an array picks several for `credentials(key)`, and `[]` picks none. Picks choose only among credentials you can Use.

## Response `200`

Success.

- object
  - `content` unknown[], required
    - unknown
  - `structuredContent` object, required
  - `isError` boolean, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/705f4f022728?raw)