> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Marketplace

## Worked marketplace samples

The endpoint list below documents every operation's parameters; this
overlay walks a listing the way a builder actually uses it: **browse the
public catalog → fetch one listing's installable config → install it →
handle the draft-listing 404**. Success envelopes are `{ data, meta }`,
error envelopes `{ error, meta }` — see [How to read a worked
sample](/guides/using-orbit-samples). The catalog read is unauthenticated;
install requires the owner, admin, or developer role and the paid listing
credits/debits the org wallet on install.

Every response carries `meta.request_id`. Quote the request id when you
report a listing that was approved but the install fails, or an install
that deducted the wallet without returning the agent it materialised.

### 1. Browse the public catalog

`GET /api/v1/marketplace` returns the catalog's published listings.
No authentication is required; draft, pending-review, and rejected
listings are never exposed. Page forward with the cursor from
`meta.pagination.cursor`, and narrow the catalog with `type`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/marketplace?type=agent_template" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/marketplace?type=agent_template",
    {
      headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
    },
  );
  console.log(await res.json());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "data": {
    "listings": [
      {
        "id": "mkl_8fb2d1b7c00c4ec9",
        "name": "Cart abandonment copilot",
        "type": "agent_template",
        "status": "published",
        "price_usd": 0,
        "author_org": "Orbit Labs"
      }
    ],
    "pagination": { "cursor": null, "has_more": false }
  },
  "meta": {
    "request_id": "req_mkt_list",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}
```

### 2. Fetch one listing's config

`GET /api/v1/marketplace/{id}` returns one published listing with the
full `config` — the payload installing copies into your workspace. The
agent definition, flow graph, integration settings, and tool pack are
all readable on a published listing; never place API keys or other
secrets in a submitted `config`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/marketplace/mkl_8fb2d1b7c00c4ec9" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/marketplace/mkl_8fb2d1b7c00c4ec9",
    {
      headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
    },
  );
  console.log(await res.json());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "data": {
    "listing": {
      "id": "mkl_8fb2d1b7c00c4ec9",
      "name": "Cart abandonment copilot",
      "type": "agent_template",
      "status": "published",
      "config": {
        "agent": { "model": "orbit-meditate-1", "persona": "helper" }
      }
    }
  },
  "meta": {
    "request_id": "req_mkt_get",
    "timestamp": "2026-08-26T12:01:00.000Z"
  }
}
```

### 3. Install a listing

`POST /api/v1/marketplace/{id}/install` materialises a published listing
into your workspace. An agent template comes in as a new `draft` agent;
other types copy their configuration directly. An identical install
returns the existing artifact — the POST is a one-shot idempotent.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    "https://api.orbit.devotel.io/api/v1/marketplace/mkl_8fb2d1b7c00c4ec9/install" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY" \
    -H "Idempotency-Key: mkt-install-2026-08-26-0001"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch(
    "https://api.orbit.devotel.io/api/v1/marketplace/mkl_8fb2d1b7c00c4ec9/install",
    {
      method: "POST",
      headers: {
        "X-API-Key": process.env.ORBIT_API_KEY!,
        "Idempotency-Key": "mkt-install-2026-08-26-0001",
      },
    },
  );
  console.log(await res.json());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "data": {
    "install": {
      "id": "inst_9e8d7c6b5a4f3021",
      "listing_id": "mkl_8fb2d1b7c00c4ec9",
      "resource_id": "agt_9e8d7c6b5a4f3021",
      "resource_type": "agent"
    }
  },
  "meta": {
    "request_id": "req_mkt_install",
    "timestamp": "2026-08-26T12:02:00.000Z"
  }
}
```

### 4. Errors

Errors follow the `{ error, meta }` envelope. The failure every
integrator hits:

**404 — draft, pending, or rejected listing.** The route never leaks an
unapproved config through a guessed id; fetch `GET
/api/v1/marketplace/mine` for any lifecycle state your own org authored.

```json 404 theme={null}
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "No marketplace listing with that id exists, or the listing is not yet published.",
    "status": 404
  },
  "meta": {
    "request_id": "req_mkt_err",
    "timestamp": "2026-08-26T12:03:00.000Z"
  }
}
```