Projects and keyword lists
Find campaigns, read dashboard activity, and manage saved keywords.
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.
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/projectswith{"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 inproject.id. - To read one campaign, use
GET /api/projects/{projectId}. To change its name or domain, send either field in a JSON body toPATCH /api/projects/{projectId}. Both return aprojectobject. - To archive a campaign, send
POST /api/projects/{projectId}/archive. Find archived campaigns usingstatus=archivedon the list request. UsePOST /api/projects/{projectId}/restoreto 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.
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.