---
title: "Opt this install into the public ranking"
method: POST
path: "/api/ranking/opt-in"
tags: ["Telemetry"]
---

# Opt this install into the public ranking

`POST /api/ranking/opt-in`

## Request

- Base URL: `http://localhost:3013`
- URL: `http://localhost:3013/api/ranking/opt-in`
- Auth: HTTP bearer

Builds the telemetry_ranking listing from the organization name and website plus the chosen category, stores it, turns PUBLIC_RANKING_ENABLED on and sends ranking.opted_in. That is the whole opt-in: the install shows on agent-swarm.dev/ranking at the next hourly refresh.

## Request body

- object
  - `category` 'engineering' | 'product' | 'marketing' | 'support' | 'operations' | 'other', required
  - `subcategory` string, nullable
  - `description` string, nullable
  - `sourceCodeUrl` string, nullable

## Response `200`

Opted in

- object
  - `domain` string, required
  - `listing` object, required
    - `v` 1, required
    - `name` string, required
    - `domain` string, required
    - `category` 'engineering' | 'product' | 'marketing' | 'support' | 'operations' | 'other', required
    - `subcategory` string, nullable, required
    - `description` string, nullable, required
    - `sourceCodeUrl` string, nullable, required
    - `updatedAt` string, required
  - `verifyUrl` string, required

## Other responses

- `400`: A listing field is invalid
- `401`: Unauthorized
- `403`: Only a config admin can opt in
- `409`: telemetry_off: telemetry is off or the install has no ID. org_identity_missing: the organization name or website is not set (`missing` lists which).

## Changes

- **2026-10-19** `915daaf44761`: 4 breaking
  - removed the required property `claim` from the response with the `200` status
  - removed the required property `fileJson` from the response with the `200` status
  - removed the required property `listing/claim` from the response with the `200` status
  - removed the required property `prUrl` from the response with the `200` status
- **2026-10-19** `9cbdf0c80fac`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/ranking/opt-in/post.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) - [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) - [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/7e4c7198192a?raw)