# Projects and keyword lists

> Find campaigns, read dashboard activity, and manage saved keywords.

Canonical: https://docs.georanker.com/docs/seo-tools-api-projects-and-lists

A project is a campaign. Use its UUID to find reports, read dashboard activity and save keyword lists for the website you track. The examples assume your SEO Tools API key is available in `SEO_TOOLS_API_KEY`.

## Find or create a project

List the organization's projects with `GET /api/projects`. This example supplies the `q` search term and filters by active status. Save the matching `projects[].id` as `PROJECT_ID` for later requests.

```sh
curl --get 'https://seoapi.georanker.com/api/projects' \
  --header "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  --data-urlencode 'status=active' \
  --data-urlencode 'q=Example Hotels'
```

* To create a campaign, send `POST /api/projects` with `{"name":"Example Hotels","domain":"example.com"}`. The name must have at least two characters. The domain is optional. A successful request returns HTTP 201 with the new UUID in `project.id`.
* To read one campaign, use `GET /api/projects/{projectId}`. To change its name or domain, send either field in a JSON body to `PATCH /api/projects/{projectId}`. Both return a `project` object.
* To archive a campaign, send `POST /api/projects/{projectId}/archive`. Find archived campaigns using `status=archived` on the list request. Use `POST /api/projects/{projectId}/restore` to reactivate one.

## Read the project dashboard

| Request                                                  | Response                                                                                |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `GET /api/projects/{projectId}/dashboard/kpis`           | Integer counts for `totalReports`, `activeMonitors`, `pendingAlerts` and `creditsUsed`. |
| `GET /api/projects/{projectId}/dashboard/recent-reports` | Recent report records in `reports`.                                                     |
| `GET /api/projects/{projectId}/dashboard/recent-alerts`  | Recent alert records in `alerts`.                                                       |
| `POST /api/projects/{projectId}/alerts/mark-all-read`    | Marks every alert for this project as read and returns `ok`.                            |

## Save and maintain a keyword list

Save terms you want to revisit in a named list. Creating the list stores those terms. To run keyword research, submit a separate report request.

```sh
curl --request POST "https://seoapi.georanker.com/api/projects/$PROJECT_ID/keyword-lists" \
  --header "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name":"City hotels","description":"Terms for the autumn campaign","keywords":[{"term":"hotels in Lisbon"},{"term":"hotels in Porto"}]}'
```

The required fields are `name` and `keywords`. HTTP 201 returns the list UUID in `id`. Use that ID for subsequent edits.

| Task                        | Request                                       | Body or result                                                                                                          |
| --------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Find the project's lists    | `GET /api/projects/{projectId}/keyword-lists` | Returns a `lists` array.                                                                                                |
| Read a saved list           | `GET /api/keyword-lists/{id}`                 | Returns the list record directly, including its keywords. A keyword can include `term`, `country`, `volume` and `tags`. |
| Rename or describe the list | `PATCH /api/keyword-lists/{id}`               | Send `name`, `description` or both.                                                                                     |
| Add a term                  | `POST /api/keyword-lists/{id}/keywords`       | For example, send `{"keywords":[{"term":"hotels in Faro"}]}`.                                                           |
| Replace the terms           | `PUT /api/keyword-lists/{id}/keywords`        | Send the complete set of terms to keep in the same `keywords` format.                                                   |
| Delete the list             | `DELETE /api/keyword-lists/{id}`              | Returns `ok` on success.                                                                                                |

Viewers receive HTTP 403 when creating or deleting a list. Members can delete lists they created. For deletion, HTTP 404 can mean the list is missing or the caller lacks permission.

[SEO Tools API overview](https://docs.georanker.com/docs/seo-tools-api)
