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

# Management API

> Publish and edit your listings from scripts, CI and agents with scoped management tokens.

> This article is for API providers. It covers the tokens that let a script or an agent act on your listings — publishing an OpenAPI document, editing endpoints, reading analytics — without your login.

The Management API is the same REST the API Studio uses. A **management token** stands in for your session on those routes, and nothing else changes: the same validation, the same ownership checks, the same audit trail.

## Management tokens are not API keys

|                         | API key (`jk_…`)                          | Management token (`jm_…`)                                                           |
| ----------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------- |
| Who uses it             | A consumer calling APIs they subscribe to | You, or an agent working for you, on your own listings                              |
| Where it is checked     | The gateway                               | `app.jojapi.com` only                                                               |
| What it can reach       | The APIs the key is allowed to call       | Your listings, plans, analytics and subscribers — by scope                          |
| What it can never reach | —                                         | Payments, wallet, payouts, billing, your profile and e-mail, API keys, other tokens |

Give each script or agent its own token with only the scopes it needs, set an expiry, and revoke it when the job is done. Tokens are created in **Studio → Management API**; the token itself is shown once.

## Scopes

| Scope                | Allows                                                                                                            |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `listings:read`      | Read your APIs, endpoints, plans, objects and FAQs                                                                |
| `listings:write`     | Create and edit APIs, endpoints, parameters, responses, groups, targets, FAQs and objects; run imports            |
| `plans:write`        | Create and change plans, quotas, per-endpoint pricing and agent payments — including an import that creates plans |
| `analytics:read`     | Traffic, transactions, request logs and the Studio dashboard                                                      |
| `subscriptions:read` | Your subscribers and their subscriptions                                                                          |

Deleting an API is never available to a token; do that in the Studio.

## Calling it

Send the token as a bearer token to the Studio's REST routes under `https://app.jojapi.com/rest/`:

```bash theme={null}
curl https://app.jojapi.com/rest/v2/ProviderApis \
  -H "Authorization: Bearer jm_…"
```

If a proxy in front of your script strips `Authorization`, the header `X-Management-Token: jm_…` is accepted too.

Answers are JSON with a `status` field; the HTTP status is 200 for every answer the application produced, so read `status`, not the code:

| `status`             | Meaning                                                                                                |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| `success`            | Done; the rest of the body is the route's answer                                                       |
| `unauthorized`       | Bad, expired or revoked token — or a route that is not part of the Management API (`route` says which) |
| `insufficient_scope` | The token lacks a scope the route needs; `required_scopes` and `token_scopes` say what is missing      |
| anything else        | The route's own validation, exactly as the Studio would show it                                        |

## Routes

Every route takes and returns JSON. `GET` routes take their parameters in the query string; `POST` routes take a JSON body. `slug` is the listing's slug — the last part of its Studio URL.

### Listings

| Route                                                                                                                                                             | Scope            | What it does                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------- |
| `GET v2/ProviderApis`                                                                                                                                             | `listings:read`  | Your listings                                     |
| `GET v2/provider-api?slug=`                                                                                                                                       | `listings:read`  | One listing with its endpoints                    |
| `GET v2/provider/api-endpoint?slug=&method=&url_path=`                                                                                                            | `listings:read`  | One endpoint in full: parameters, body, responses |
| `GET v2/provider-api-targets?slug=`                                                                                                                               | `listings:read`  | The listing's upstream targets                    |
| `GET v2/studio/api-plans?slug=` · `api-objects` · `api-faqs`                                                                                                      | `listings:read`  | Plans, billable objects, FAQs                     |
| `POST v2/provider/add-api`                                                                                                                                        | `listings:write` | Create a listing                                  |
| `POST v2/update-api-details` · `update-api-about`                                                                                                                 | `listings:write` | Name, description, about text                     |
| `POST v2/provider/add-endpoint` · `provider/update-endpoint-details` · `provider/delete-endpoint` · `provider/duplicate-endpoint`                                 | `listings:write` | Endpoints                                         |
| `POST v2/update-url-parameters` · `update-header-parameters` · `update-path-parameters` · `update-endpoint-body`                                                  | `listings:write` | An endpoint's parameters and body                 |
| `POST v2/update-endpoint-responses` · `upsert-endpoint-response`                                                                                                  | `listings:write` | Documented responses and examples                 |
| `POST v2/create-api-endpoint-group` · `update-endpoint-group` · `delete-endpoint-group` · `move-endpoint-to-group` · `set-group-order` · `update-endpoint-orders` | `listings:write` | Grouping and order                                |
| `POST v2/update-api-target-v2` · `delete-api-target` · `set-custom-gateway-prefix`                                                                                | `listings:write` | Upstream targets                                  |
| `POST v2/studio/create-api-faq` · `update-api-faq` · `delete-api-faq` · `update-api-faq-orders`                                                                   | `listings:write` | FAQs                                              |
| `POST v2/studio/create-object` · `update-object` · `delete-object` · `set-api-features`                                                                           | `listings:write` | Billable objects and plan features                |
| `POST v2/provider/listing-resubmit`                                                                                                                               | `listings:write` | Resubmit a listing for review                     |

### Imports — publishing an OpenAPI document

The fastest way to keep a listing in step with your code is to publish its OpenAPI document. An import never touches an existing endpoint's blocked/hidden flags, its group or its plans unless you ask it to.

| Route                                                                                     | Scope                                                                     | What it does                                                                                                                                             |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST v2/import/preview`                                                                  | `listings:write`                                                          | `{slug, bundle}` → what would be new, changed, unchanged and missing                                                                                     |
| `POST v2/import/apply`                                                                    | `listings:write` (+ `plans:write` with `import_plans` or `publish_plans`) | `{slug, bundle, new_hidden, overwrite_changed, hide_missing, update_meta, use_groups, import_plans, publish_plans}` → writes the diff in one transaction |
| `POST v2/import/fetch` · `import/upload` · `import/fetch-rapidapi` · `import/fetch-apify` | `listings:write`                                                          | Fetch or upload a source document into a snapshot                                                                                                        |

`bundle` is a JSON **string** in the import engine's source-agnostic shape:

```json theme={null}
{
  "meta": { "name": "…", "description": "…" },
  "endpoints": [{
    "method": "GET", "url_path": "/v1/serp", "name": "Full SERP", "description": "…", "group": "",
    "url_parameters": [{ "key": "query", "name": "", "description": "…", "example": "best running shoes",
                         "value_type": "string", "enum_values": null, "default_value": "", "required": true }],
    "header_parameters": [], "path_parameters": [], "body": null,
    "responses": [{ "status": "200", "description": "…", "schema": null,
                    "examples": [{ "name": "success", "summary": "", "description": "", "example": "{…}" }] }]
  }]
}
```

`value_type` is one of `string`, `enum`, `number`, `integer`, `boolean`, `date`, `time`, `object`, `array`, `geopoint`. Preview first, read the diff, then apply.

### Pricing

| Route                                                                                                                             | Scope         |
| --------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `POST v2/studio/create-api-plan` · `update-api-plan` · `delete-api-plan` · `update-plan-display` · `add-api-plan-object`          | `plans:write` |
| `POST v2/provider/bulk-update-endpoint-billing` · `provider/bulk-update-endpoint-agent-price` · `provider/set-api-agent-payments` | `plans:write` |
| `POST v2/set-user-custom-api-plan` · `studio/grant-quota`                                                                         | `plans:write` |

### Analytics and subscribers

| Route                                                                                                                                     | Scope                |
| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `GET v2/studio/dashboard` · `studio-analytics-api?slug=` · `studio-low-uptime-endpoints` · `request-logs-studio` · `ProviderTransactions` | `analytics:read`     |
| `GET v2/ProviderSubscriptions` · `pending-transfers`                                                                                      | `subscriptions:read` |

## Audit and limits

Every request made with a token is logged with its outcome — allowed, refused route, missing scope — and kept for 90 days; the token's **last used** stamp is on the Management API page. A token can be valid for at most a year, an account can hold 20 live tokens, and the import routes share the Studio's limit of 200 imports an hour.

Keep tokens where your scripts read secrets from, never in a repository. If one leaks, revoke it on the Management API page; the revocation is immediate.