The API can read the same list your Actions page shows and the Top opportunities on your Overview. With a key that has the Read and write permission, it can also mark an action done or dismissed. For keys and how to send a request, see API access. That article describes reading. This article covers the changes a Read and write key can make.
Addresses
| Method and address | What it does |
|---|---|
GET /projects/{id}/actions | Your actions, best first, each with its id and status (new, in_progress, done or dismissed). Add status=new,in_progress to list only some. Actions below the list's cut are left out unless you add include_all=true, as Show all does on the page |
GET /projects/{id}/opportunities | The week's top five actions, content gaps and pages losing citations, ranked by impact, as on your Overview |
POST /projects/{id}/actions/status | Marks one action done or dismissed, or back to new. Send id (from the actions list) and status (done, dismissed or new) |
The lists take the same from, to and engines as the other addresses, and the actions list takes limit and cursor. Each fix in GET /projects/{id}/fixes also carries its id.
Make a key that can write
Go to Settings, then API keys. Choose Read and write under Permissions and generate the key. Read only is the default. Only a workspace Admin can make keys.
A change made with the key counts as a change by the person who made the key, with the rights of a Member. It changes the status exactly as the Actions page does, and shows in the audit log with the source API and the key's name.
A Read and write key is not limited to actions. It can also make any other change the API allows, including changes switched on after you made the key. Keep it to the scripts that need it, and revoke it in Settings, under API keys, when you no longer do.
Try a change first
Add ?dry_run=true to see what would change. Nothing is changed, and any key can send one.
Errors
Every error is a JSON object with a short error code and a message that says what to do. Test for the code, not the message.
| Status | Code | What it means |
|---|---|---|
| 400 | bad_request | The body or a query value is not valid, such as a status the address does not take |
| 400 | bad_cursor | The cursor is not one the API gave you. Leave cursor out to start again |
| 401 | unauthenticated | No key was sent. Send Authorization: Bearer YOUR_KEY |
| 401 | invalid_key | The key is not shaped like one of ours, is unknown, or has been revoked |
| 401 | key_expired | The key's expiry date has passed. Generate a new key |
| 403 | insufficient_scope | The key is read only. Changes need a key with the Read and write permission |
| 403 | role_read_only | The person who made the key is not an Admin or Member of the workspace now |
| 403 | workspace_suspended | The key's workspace is suspended |
| 403 | no_workspace | The key's workspace was not found |
| 404 | not_found | No such project for this key, or no action with that id in this project for the period |
| 405 | method_not_allowed | This address does not take that method |
| 429 | rate_limited | A request limit is used up. Wait for Retry-After seconds |
| 503 | api_not_available | The API is not available right now |
| 503 | database_not_configured | The API is not available right now |