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

# Browse, install, and publish marketplace templates

> Find published agent templates, flow templates, and integrations in the developer marketplace, install one into your workspace, and submit your own listing for review.

# Browse, install, and publish marketplace templates

The developer marketplace is a catalog of agent templates, flow templates, integrations, and agent tool packs published by Devotel and by other Orbit builders. Browse the catalog without any credentials, install a listing into your workspace in one call, or publish something you built for other tenants to install. This guide walks through all three flows end to end.

The write paths (creating, submitting, installing) require an `owner`, `admin`, or `developer` role on the calling key or session. The public read paths need no authentication at all.

## Browse the public catalog

`GET /marketplace` and `GET /marketplace/:id` are public — no API key, no session. Both return published listings only, so you can embed either call in a public page or a CLI without shipping a credential.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/marketplace?limit=25"
```

Narrow the catalog with `type` — `agent_template`, `flow_template`, `integration`, or `agent_tool`:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/marketplace?type=flow_template"
```

Page forward with the `cursor` from the previous response's `meta.pagination.cursor`:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/marketplace?cursor=2026-04-16T00:00:00.000Z&limit=25"
```

A listing row carries `id`, `type`, `name`, `description`, `installs`, `status`, `authorOrgId`, and timestamps. The installable `config` payload is omitted from list rows — fetch it on the detail endpoint:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/marketplace/mkt_8fk2d93"
```

The detail response includes the full `config` blob — the agent definition, flow graph, integration settings, or tool definition that installing copies into your workspace. Read it before you install; it is exactly what ends up in your tenant.

## Only published listings are visible

The public endpoints answer published listings and nothing else. Drafts, submissions awaiting review, and rejected listings return 404 on the detail endpoint and never appear in the list — even if you know the id, and even if you pass `?status=draft` on the list call (the public query ignores `status` entirely). Unpublished content never leaks to unauthenticated callers by design, so treat a 404 here as "not published", not "not found".

To see your own organization's drafts and submissions across every status, use the author-scoped list with your key:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/marketplace/mine?status=pending_review" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

`/marketplace/mine` accepts `status` (`draft`, `pending_review`, `published`, `rejected`) and `type`, and is always scoped to your own organization.

## Install a template into your workspace

Installing is a one-time copy, not a live link. The moment the install completes, the template's configuration lands in your tenant as your own resource, and later edits to the marketplace listing never touch your copy — it cannot drift when the author updates the listing, and the author cannot change what you already installed.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/marketplace/mkt_8fk2d93/install" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

What lands depends on the listing type:

* An **agent template** materializes as a new agent in your workspace in `draft` status. The response's `data.id` is the new agent id, so you can link straight into the agent editor and review it before pointing traffic at it.
* Flow templates, integrations, and agent tool packs copy their configuration into your tenant with no agent created.

Installing the same agent template twice does not create a duplicate — the call returns the agent you installed the first time. You can safely retry an install call (for example after a timeout) and always end up with exactly one agent.

Only published listings install. A listing that is still a draft, awaiting review, or rejected returns 404, same as the public read paths.

Paid listings are charged at install: the price a builder set on their listing is deducted from your wallet before the copy is created and credited to the builder minus the platform fee, so an install either completes fully or not at all.

## Rate limits

Public reads and author writes run on separate per-route buckets:

| Surface                                                | Bucket                 |
| ------------------------------------------------------ | ---------------------- |
| `GET /marketplace` and `GET /marketplace/:id` (public) | 60 requests per minute |
| Create, update, delete, install                        | 10 requests per minute |

Writes are deliberately tighter than reads — the catalog is meant to be browsed far more often than edited. A rejected request returns 429 with a `Retry-After` header; queue publishes on a delay rather than retrying in a tight loop.

## Publish your own listing

Publishing is a four-step loop: create a draft, refine it, submit it for review, and track the verdict.

**1. Create the draft.** `type` and `name` are required; the listing starts in `draft` and stays invisible to everyone but your organization until a reviewer approves it.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/marketplace" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "agent_template",
    "name": "Tier-1 support triage",
    "description": "Answers billing and delivery questions, escalates everything else to a human.",
    "config": {
      "systemPrompt": "You are a tier-1 support agent. Answer billing and delivery questions from the knowledge base; hand off anything else.",
      "model": "claude-sonnet-4-6",
      "tools": ["search_knowledge_base", "create_ticket"]
    }
  }'
```

The `config` blob becomes publicly readable the moment the listing goes live, so never put API keys, webhook secrets, or credentials in it (agent tool listings are hard-rejected on a secret field). Keep the creation response's `data.id` — you need it for updates, submission, and deletion.

**2. Refine the draft.** Update the name, description, or `config` as often as you like while the listing is yours alone:

```bash theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/marketplace/mkt_8fk2d93" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Answers billing and delivery questions; escalates everything else." }'
```

**3. Submit for review.** Move the listing to `pending_review` — that is the whole submission flow:

```bash theme={null}
curl -X PUT "https://api.orbit.devotel.io/api/v1/marketplace/mkt_8fk2d93" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "pending_review" }'
```

Setting `status` to `published` or `rejected` yourself returns 403 — those two values are verdicts only a platform reviewer can write. To pull a submission back out of the queue, set `status` back to `draft`.

**4. Track the verdict.** Poll `/marketplace/mine` for the status change:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/marketplace/mine?status=published" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

Approve promotes the listing to `published` — it appears in the public catalog within a minute and becomes installable by any tenant. Reject stamps it `rejected` along with the reviewer's notes, which show up on your listing row; read the note, fix the listing, and resubmit by moving it back to `pending_review`.

You can also delete a listing entirely (`DELETE /marketplace/:id`). Deleting removes it from the catalog so it can no longer be installed, but tenants that already installed it keep their copy — installs are snapshots, not subscriptions.

## Review listings as an administrator

Organization administrators work the moderation queue in the admin console at **Dashboard → Marketplace**: a pending-review list (oldest submission first) with approve and reject actions, a preview of each listing's full `config` before the verdict, and the published catalog with a takedown action.

Two rules keep the queue trustworthy:

* **Rejections always carry a note.** The reject action requires the reviewer to write a reason, and that note lands on the author's listing row — a rejection with no context would force the submitter to guess what to fix.
* **Published listings can be pulled after the fact.** A takedown flips a live listing back out of the catalog and always requires a reason, so the audit trail explains why a listing that already shipped was removed.

## Frequently asked questions

### Can I hide my listing from the public catalog while I iterate?

Yes — keep it in `draft`. Only your organization sees drafts, and you can move back to `draft` even after submitting, as long as the review has not landed yet.

### If the author updates their listing after I installed it, what happens to my copy?

Nothing. The install copied the configuration at that moment, and the copy is yours. A later version is only available if you install the listing again.

### I keep getting 404 on a listing id I know exists. Why?

The listing is not published. Drafts, pending submissions, and rejected listings return 404 to every caller except the author's own `/marketplace/mine` path and the admin moderation queue.

### What happens if a review approves and rejects the same listing twice?

It cannot. The queue only accepts submissions that are still `pending_review` — once a verdict lands, a second attempt to review the same listing fails instead of overwriting the first.

## See also

* [Developer Portal](/guides/developer-portal) — API keys, the try-it console, and OAuth apps for requesting scoped access to a customer's org
* [Authentication](/authentication) — API key formats and roles for the write endpoints
* [API Reference overview](/api-reference/overview) — the full endpoint catalog
* [Rate limits](/guides/rate-limits) — how buckets, 429s, and `Retry-After` behave across the API