> For the complete documentation index, see [llms.txt](https://docs.shortcutco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shortcutco.com/developers/api-reference/reference/actions.md).

# Actions

Changes waiting for a person's approval.

When a token or app is set to Do after approval in an area, a write there answers 202 with an action instead of making the change. A company admin approves or rejects it in Settings > API & integrations; the action then carries the write's own response.

Fields: [The action object](https://docs.shortcutco.com/developers/reference/objects/action).

## List this connection's actions

> Writes this token or app asked for that waited for a company admin's approval, newest first: pending, approved, rejected, expired, and the result of each one that ran. Only the asking connection's own actions are listed. Needs no scope.\
> \
> Returns a list of \[action objects]\(<https://docs.shortcutco.com/developers/reference/objects/action>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Actions","description":"When a token or app is set to Do after approval in an area, a write there answers 202 with an action instead of making the change. A company admin approves or rejects it in Settings > API & integrations; the action then carries the write's own response.\n\nFields: [The action object](https://docs.shortcutco.com/developers/reference/objects/action)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Action":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The action's id. `GET /v1/actions/{id}` (MCP `get_action`) says where it stands."},"object":{"type":"string","const":"action","description":"Always `action`."},"status":{"type":"string","enum":["pending","approved","rejected","expired","succeeded","failed"],"description":"`pending`: waiting for a company admin. `approved`: approved and running; one still `approved` after five minutes was interrupted, and a company admin can try it again in Settings (a write that already went through is not repeated). `succeeded` or `failed`: it ran; `result` has the response. `rejected`: the admin said no. `expired`: nobody decided within 72 hours."},"operation":{"type":"string","description":"The operation that was asked for, e.g. `estimates.send`."},"summary":{"type":"string","description":"What will happen, in a sentence."},"area":{"type":"string","description":"The area whose level asked for approval, e.g. `messages`."},"preview":{"anyOf":[{},{"type":"null"}],"description":"What the write would return, from a dry run, when the operation has one; null otherwise."},"approvalUrl":{"type":"string","format":"uri","description":"Where a company admin approves or rejects it. Share it with the person you are working for."},"createdAt":{"type":"string","format":"date-time","description":"When it was asked for, ISO 8601 in UTC."},"expiresAt":{"type":"string","format":"date-time","description":"When it stops being approvable."},"decidedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was approved or rejected."},"result":{"anyOf":[{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status the write answered with."},"body":{"description":"The write's response body, as the operation itself returns it."}},"required":["status"],"additionalProperties":false},{"type":"null"}],"description":"The write's response once it ran; null before."}},"required":["id","object","status","operation","summary","area","approvalUrl","createdAt","expiresAt","decidedAt","result"],"additionalProperties":false,"description":"A write waiting for, or decided by, a person."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/actions":{"get":{"operationId":"actions.list","tags":["Actions"],"summary":"List this connection's actions","description":"Writes this token or app asked for that waited for a company admin's approval, newest first: pending, approved, rejected, expired, and the result of each one that ran. Only the asking connection's own actions are listed. Needs no scope.\n\nReturns a list of [action objects](https://docs.shortcutco.com/developers/reference/objects/action).","parameters":[{"name":"status","in":"query","required":false,"description":"Only actions with this status.","schema":{"type":"string","enum":["pending","approved","rejected","expired","succeeded","failed"]}},{"name":"limit","in":"query","required":false,"description":"How many to return, up to 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Action"}},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```

## Get an action

> One write this token or app asked for that waited for approval: whether a company admin approved or rejected it, and once it ran, the write's own response in \`result\`. Another connection's action is a 404. Needs no scope.\
> \
> Returns \[the action object]\(<https://docs.shortcutco.com/developers/reference/objects/action>).

```json
{"openapi":"3.1.0","info":{"title":"Shortcut API","version":"v1"},"tags":[{"name":"Actions","description":"When a token or app is set to Do after approval in an area, a write there answers 202 with an action instead of making the change. A company admin approves or rejects it in Settings > API & integrations; the action then carries the write's own response.\n\nFields: [The action object](https://docs.shortcutco.com/developers/reference/objects/action)."}],"servers":[{"url":"https://api.shortcutco.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"scut_<env>_<id>_<secret>","description":"A workspace API token. Each operation lists the scopes it needs; `write` implies `read`, and `send`/`complete` are never implied."}},"headers":{"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests allowed in the tightest window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in that window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Seconds until that window resets."}},"schemas":{"Action":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The action's id. `GET /v1/actions/{id}` (MCP `get_action`) says where it stands."},"object":{"type":"string","const":"action","description":"Always `action`."},"status":{"type":"string","enum":["pending","approved","rejected","expired","succeeded","failed"],"description":"`pending`: waiting for a company admin. `approved`: approved and running; one still `approved` after five minutes was interrupted, and a company admin can try it again in Settings (a write that already went through is not repeated). `succeeded` or `failed`: it ran; `result` has the response. `rejected`: the admin said no. `expired`: nobody decided within 72 hours."},"operation":{"type":"string","description":"The operation that was asked for, e.g. `estimates.send`."},"summary":{"type":"string","description":"What will happen, in a sentence."},"area":{"type":"string","description":"The area whose level asked for approval, e.g. `messages`."},"preview":{"anyOf":[{},{"type":"null"}],"description":"What the write would return, from a dry run, when the operation has one; null otherwise."},"approvalUrl":{"type":"string","format":"uri","description":"Where a company admin approves or rejects it. Share it with the person you are working for."},"createdAt":{"type":"string","format":"date-time","description":"When it was asked for, ISO 8601 in UTC."},"expiresAt":{"type":"string","format":"date-time","description":"When it stops being approvable."},"decidedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was approved or rejected."},"result":{"anyOf":[{"type":"object","properties":{"status":{"type":"integer","description":"The HTTP status the write answered with."},"body":{"description":"The write's response body, as the operation itself returns it."}},"required":["status"],"additionalProperties":false},{"type":"null"}],"description":"The write's response once it ran; null before."}},"required":["id","object","status","operation","summary","area","approvalUrl","createdAt","expiresAt","decidedAt","result"],"additionalProperties":false,"description":"A write waiting for, or decided by, a person."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Error family, such as `invalid_request` or `permission`."},"code":{"type":"string","description":"Specific error code; see the errors page."},"message":{"type":"string","description":"A human-readable explanation."},"param":{"type":"string","description":"The input the error is about, such as `query.limit`."},"requiredScope":{"type":"string","description":"The scope the token is missing."},"requestId":{"type":"string","description":"Quote this id to support."},"docs":{"type":"string","description":"Link to the error's documentation."}},"required":["type","code","message","requestId","docs"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthenticated":{"description":"The token is missing, invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SubscriptionRequired":{"description":"The workspace's subscription needs attention.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The token is missing a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such object in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Rate limited; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalError":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"Temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/actions/{id}":{"get":{"operationId":"actions.get","tags":["Actions"],"summary":"Get an action","description":"One write this token or app asked for that waited for approval: whether a company admin approved or rejected it, and once it ran, the write's own response in `result`. Another connection's action is a 404. Needs no scope.\n\nReturns [the action object](https://docs.shortcutco.com/developers/reference/objects/action).","parameters":[{"name":"id","in":"path","required":true,"description":"The object's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Action"},"meta":{"type":"object","properties":{},"additionalProperties":true,"description":"Facts about this request beside the object, such as `alreadyReminded` on a repeated reminder. Present only when there is something to report."}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthenticated"},"402":{"$ref":"#/components/responses/SubscriptionRequired"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}}}}}}
```
