Labels

List keyword labels

seo_rankings.labels.list

Lists the organization's keyword labels (name, color, order) in the order of the app, paginated by cursor. Labels group tracked keywords (by topic, landing page, priority…) and filter seo_rankings.keywords.list; assign them with seo_rankings.keywords.bulk.set_labels. Create them with seo_rankings.labels.create, rename, recolor or move them with seo_rankings.labels.update and delete them with seo_rankings.labels.delete. created_by_name is the name of who created it (null for the ones created in the app, which does not record it).

Scope

seo_rankings:read

Permission

View the module

MCP tool

seo_rankings_labels_listOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.labels.list".

Declared cost: up to 100 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/seo/rankings/labels" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/seo/rankings/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a keyword label

seo_rankings.labels.create

Creates a keyword label at the end of the organization's list, the same labels the Rankings screen manages: name (1 to 60 characters) and an optional hex color such as #3b82f6 (without it, the color of the app's palette for its position). Like the screen, it does not check for another label with the same name: look it up first with seo_rankings.labels.list. Assign it with seo_rankings.keywords.bulk.set_labels or label_ids when adding keywords. Returns label_id and the label. Requires edit access to Rankings.

Scope

seo_rankings:write

Permission

Edit in the module

MCP tool

seo_rankings_labels_createOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.labels.create".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/seo/rankings/labels" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/seo/rankings/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME"
}'

Rename, recolor or move a keyword label

seo_rankings.labels.update

Changes a keyword label, sent inside updates: name (1 to 60 characters), a hex color such as #3b82f6 and order (its position in the list, 0 = first; the other labels keep theirs, as when the app saves one label). The keywords that carry it keep it. Setting what it already has changes nothing (changed false, no write). 404 rank_label_not_found when the label is not in this organization. Unknown fields are rejected. Returns the label and changed. Requires edit access to Rankings.

Scope

seo_rankings:write

Permission

Edit in the module

MCP tool

seo_rankings_labels_updateOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.labels.update".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/seo/rankings/labels/{label_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/seo/rankings/labels/{label_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a keyword label

seo_rankings.labels.delete

Deletes a keyword label and takes it off every keyword of the organization that carries it, as the Rankings screen does; the keywords themselves and their history are not touched. The label stays 30 days in the trash: restored (platform.trash.restore), it comes back with its id, name, color and order but not on the keywords, so reassign it with seo_rankings.keywords.bulk.set_labels. Outside the app it needs a dry run, which names the label and counts the keywords that lose it, and its confirm_token. 404 rank_label_not_found when the label is not in this organization. Returns ok and keywords_updated. Requires edit access to Rankings.

With an API key, this DELETE runs directly: the record stays 30 days in the trash and the response carries its trash_item_id. With an OAuth token, and through the MCP, it needs dry_run → confirm_token.

Scope

seo_rankings:write and “Allow deletions” (seo_rankings:delete in OAuth)

Permission

Edit in the module

MCP tool

seo_rankings_labels_deleteOn the full surface; on the compact one, mb_execute_operation with id: "seo_rankings.labels.delete".

Declared cost: up to 501 reads and 501 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/seo/rankings/labels/{label_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/seo/rankings/labels/{label_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"