Favorites

Saved listings and their folders.

GET `/favorites`

Favorite listings

Scope: listings:read, or the broad read. Newest first, by id.

Active public listings only.

Parameters

Name	Where	Description
`cursor`	query	`meta.next_cursor` from the previous page. Up to 1024 characters.
`limit`	query	Page size. Above 100 is treated as 100. At least 1. Default `25`.
`folder_id`	query	One of your own folders. At least 1.
`If-None-Match`	header	An ETag from an earlier response.

Example request

curl "https://www.seoclerk.com/api/v1/favorites" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

Field	Type	Description
`id`	integer
`service_id`	integer
`title`	string
`created_at`	timestamp or null

{
    "data": [
        {
            "id": 1024,
            "service_id": 1024,
            "title": "Logo design",
            "created_at": "2026-10-10T14:03:22Z"
        }
    ],
    "meta": {
        "limit": 1,
        "next_cursor": "string",
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
422	`bad_cursor` `invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`

POST `/favorites`

Save a listing

Scope: account:write, or the broad write. Idempotency-Key is required.

A listing already saved answers 200 with the same favourite. The listing's owner is alerted, at most once a day for the same member and listing, never for your own.

Parameters

Name	Where	Description
`Idempotency-Key` required	header	Makes a retry safe. Required on every POST. Must match `^[A-Za-z0-9_.-]{1,64}$`.

Request body

Field	Type	Description
`service_id` required	integer	The listing to save. 1 to 4294967295.

Example request

curl -X POST "https://www.seoclerk.com/api/v1/favorites" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: addfavorite-1" \
  -H "Content-Type: application/json" \
  -d '{"service_id":1024}'

Response 201

Field	Type	Description
`id`	integer
`service_id`	integer
`title`	string
`created_at`	timestamp or null

{
    "data": {
        "id": 1024,
        "service_id": 1024,
        "title": "Logo design",
        "created_at": "2026-10-10T14:03:22Z"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Response 200

Field	Type	Description
`id`	integer
`service_id`	integer
`title`	string
`created_at`	timestamp or null

{
    "data": {
        "id": 1024,
        "service_id": 1024,
        "title": "Logo design",
        "created_at": "2026-10-10T14:03:22Z"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`bad_json` `https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
409	`idempotency_conflict` `idempotency_in_progress` `listing_unavailable`
413	`body_too_large`
415	`unsupported_media_type`
422	`bad_idempotency_key` `idempotency_key_required` `invalid_fields` `invalid_parameter`
429	`rate_limited`
500	`internal_error`
503	`write_storage_unavailable`

GET `/favorites/folders`

Favorite folders

Scope: listings:read, or the broad read. Newest first, by id.

Parameters

Name	Where	Description
`cursor`	query	`meta.next_cursor` from the previous page. Up to 1024 characters.
`limit`	query	Page size. Above 100 is treated as 100. At least 1. Default `25`.
`If-None-Match`	header	An ETag from an earlier response.

Example request

curl "https://www.seoclerk.com/api/v1/favorites/folders" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

Field	Type	Description
`id`	integer
`name`	string
`public`	boolean
`color`	string or null
`created_at`	timestamp or null

{
    "data": [
        {
            "id": 1024,
            "name": "Example",
            "public": true,
            "color": "string",
            "created_at": "2026-10-10T14:03:22Z"
        }
    ],
    "meta": {
        "limit": 1,
        "next_cursor": "string",
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
422	`bad_cursor` `invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`

POST `/favorites/folders`

Make a folder

Scope: account:write, or the broad write. Idempotency-Key is required.

At most 200 folders. Tags are removed from the name and it is stored HTML-encoded, as the website stores it; reads give it encoded.

Parameters

Name	Where	Description
`Idempotency-Key` required	header	Makes a retry safe. Required on every POST. Must match `^[A-Za-z0-9_.-]{1,64}$`.

Request body

Field	Type	Description
`name` required	string	1 to 50 characters, not one of your folders already (any case). 1 to 50 characters.
`public`	boolean	Shown on your profile. Default false.

Example request

curl -X POST "https://www.seoclerk.com/api/v1/favorites/folders" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: createfavoritefolder-1" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example"}'

Response 201

Field	Type	Description
`id`	integer
`name`	string
`public`	boolean
`color`	string or null
`created_at`	timestamp or null

{
    "data": {
        "id": 1024,
        "name": "Example",
        "public": true,
        "color": "string",
        "created_at": "2026-10-10T14:03:22Z"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

Status	Codes
400	`bad_json` `https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
409	`folder_exists` `folder_limit` `idempotency_conflict` `idempotency_in_progress`
413	`body_too_large`
415	`unsupported_media_type`
422	`bad_idempotency_key` `idempotency_key_required` `invalid_fields` `invalid_parameter`
429	`rate_limited`
500	`internal_error`
503	`write_storage_unavailable`

POST `/favorites/folders/{id}/favorites`

Put a favourite in a folder

Scope: account:write, or the broad write. Idempotency-Key is required.

Both must be your own. One already in the folder is left as it is.

Parameters

Name	Where	Description
`id` required	path	At least 1.
`Idempotency-Key` required	header	Makes a retry safe. Required on every POST. Must match `^[A-Za-z0-9_.-]{1,64}$`.

Request body

Field	Type	Description
`favorite_id` required	integer	One of your favourites, as GET favorites lists it. 1 to 4294967295.

Example request

curl -X POST "https://www.seoclerk.com/api/v1/favorites/folders/1024/favorites" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: addfavoritetofolder-1" \
  -H "Content-Type: application/json" \
  -d '{"favorite_id":1024}'

Response 204

No body.

Errors

Status	Codes
400	`bad_json` `https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
409	`idempotency_conflict` `idempotency_in_progress`
413	`body_too_large`
415	`unsupported_media_type`
422	`bad_idempotency_key` `idempotency_key_required` `invalid_fields` `invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`
503	`write_storage_unavailable`

DELETE `/favorites/folders/{id}/favorites/{favorite_id}`

Take a favourite out of a folder

Scope: account:write, or the broad write. Idempotency-Key is optional.

Parameters

Name	Where	Description
`id` required	path	At least 1.
`favorite_id` required	path	At least 1.
`Idempotency-Key`	header	Makes a retry safe. Must match `^[A-Za-z0-9_.-]{1,64}$`.

Example request

curl -X DELETE "https://www.seoclerk.com/api/v1/favorites/folders/1024/favorites/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 204

No body.

Errors

Status	Codes
400	`bad_json` `https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
409	`idempotency_conflict` `idempotency_in_progress`
413	`body_too_large`
415	`unsupported_media_type`
422	`bad_idempotency_key` `invalid_fields` `invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`
503	`write_storage_unavailable`

DELETE `/favorites/{id}`

Remove a favourite

Scope: account:write, or the broad write. Idempotency-Key is optional.

Parameters

Name	Where	Description
`id` required	path	At least 1.
`Idempotency-Key`	header	Makes a retry safe. Must match `^[A-Za-z0-9_.-]{1,64}$`.

Example request

curl -X DELETE "https://www.seoclerk.com/api/v1/favorites/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 204

No body.

Errors

Status	Codes
400	`bad_json` `https_required` `key_in_query`
401	`account_unavailable` `invalid_credentials` `key_expired` `key_revoked`
403	`missing_scope`
404	`not_found`
405	`method_not_allowed`
409	`idempotency_conflict` `idempotency_in_progress`
413	`body_too_large`
415	`unsupported_media_type`
422	`bad_idempotency_key` `invalid_fields` `invalid_id` `invalid_parameter`
429	`rate_limited`
500	`internal_error`
503	`write_storage_unavailable`

Favorites

GET /favorites

Parameters

Example request

Response 200

Errors

POST /favorites

Parameters

Request body

Example request

Response 201

Response 200

Errors

GET /favorites/folders

Parameters

Example request

Response 200

Errors

POST /favorites/folders

Parameters

Request body

Example request

Response 201

Errors

POST /favorites/folders/{id}/favorites

Parameters

Request body

Example request

Response 204

Errors

DELETE /favorites/folders/{id}/favorites/{favorite_id}

Parameters

Example request

Response 204

Errors

DELETE /favorites/{id}

Parameters

Example request

Response 204

Errors

GET `/favorites`

POST `/favorites`

GET `/favorites/folders`

POST `/favorites/folders`

POST `/favorites/folders/{id}/favorites`

DELETE `/favorites/folders/{id}/favorites/{favorite_id}`

DELETE `/favorites/{id}`