---
title: "List suggested actions"
method: GET
path: "/api/v1/org-actions/proposals"
tags: ["authed"]
---

# List suggested actions

`GET /api/v1/org-actions/proposals`

## Request

- Base URL: `https://api.teaflask.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.teaflask.com/api/v1/org-actions/proposals`
- Auth: none declared

Suggested actions from scans and uploads, newest first, each as a
summary without its schemas; pass status=open for the ones waiting for
review, and read one in full with get_org_action_proposal. Approve with
its payload_fingerprint. A full page means more may exist.

## Query parameters

- `status` 'open' | 'approved' | 'dismissed' | 'withdrawn'
- `before_created_at` string, date-time, nullable: With before_id: the last row of the previous page's created_at, to read the next page.
- `before_id` string, uuid, nullable: With the sort cursor: the last row of the previous page's id.
- `limit` integer: The most suggested actions to return.

## Response `200`

Successful Response

- OrgActionProposalSummaryResponse[]
  - `id` string, uuid, required: The suggested action's id.
  - `kind` 'create' | 'update' | 'deprecate', required
  - `status` 'open' | 'approved' | 'dismissed' | 'withdrawn', required
  - `org_action_id` string, uuid, nullable, required: The catalog action an update or deprecation changes; null for a new action.
  - `title` string, required: The title the action would have.
  - `description` string, nullable, required: What an agent would read when deciding whether to call the action; null when the suggestion carries none.
  - `slug` string, nullable, required: The unique short name the action would have; null when the suggestion carries none.
  - `method` 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', required: The catalog's method whitelist: an action can only ever speak these.
  - `path_template` string, nullable, required: The endpoint path on the organization's own API, with {placeholder} segments; null when the suggestion carries none.
  - `graphql` GraphQLOperationIdentity, required: A GraphQL operation's identity without its document: what recorded agent work names the operation by.
    - `operation_name` string, required: The operation's GraphQL name, like "GetSubscription".
    - `operation_type` 'query' | 'mutation', required: The operation kinds an action can carry; a query defaults like a GET, a mutation like any other write. Subscriptions are refused.
  - `effect` 'read_only' | 'idempotent' | 'destructive', required: What calling the action does to the world — an annotation, never a policy. It feeds the policy default for rows registered without one and the approval gate's prompt tone; an explicit policy always wins, and a mutating method never defaults above ask whatever the annotation claims.
  - `policy` 'allow' | 'deny' | 'ask', required
  - `edited_at` string, date-time, nullable, required: When a member last edited the suggestion, which later scans then leave alone; null when never edited.
  - `kept` integer, required: How many member edits on the action approving keeps, because the code didn't change them.
  - `conflicts` integer, required: How many member edits the code changed too; approving needs a version picked for each, which get_org_action_proposal lists.
  - `kept_labels` string[], required: The parts approving keeps as members edited them, in words.
  - `kept_by_user_ids` string[], required: Who made the kept edits, each member once; null stands for an edit whose author isn't known.
  - `payload_fingerprint` string, required: The suggestion's version; approving sends it as reviewed_fingerprint, so only what you read is approved.
  - `provenance` ProposalProvenance, required: The evidence fields a reviewer reads off a proposal's source_ref.
    - `origin` 'inference' | 'generated' | 'graphql' | 'uploaded', required: Which kind of evidence a source_ref carries. Spec refs (the scan's extractions) are the origin-less default and never write the key — only non-spec evidence names itself.
    - `commit_sha` string, nullable, required: The commit the evidence was read at; null for uploaded files.
    - `generator_sha256` string, nullable, required: A fingerprint of the script that generated the spec; null unless the spec was generated.
    - `spec_path` string, nullable, required: The spec file's path; null for evidence read from code.
    - `set_sha256` string, nullable, required: A fingerprint of the uploaded set of files; null unless the spec was uploaded.
  - `created_at` string, date-time, required: When the suggestion was filed.

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `405`: Method not allowed
- `422`: Validation error
- `500`: Internal server error

## Changes

- **2026-11-03** `c6ac9fd6657f`: 6 info
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `401`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `403`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `404`
  - removed the `STEEP_LEARNING_DISABLED` enum value from the `error/code` response property for the response status `405`
  - …2 more

[Operation history](https://skmtc.dev/teaflask/apis/teaflask-api/changes/api/v1/org-actions/proposals/get.md)

---

[API](https://skmtc.dev/teaflask/apis/teaflask-api.md) - [All operations](https://skmtc.dev/teaflask/apis/teaflask-api/llms.txt) - [OpenAPI document](https://skmtc.dev/teaflask/apis/teaflask-api/revisions/c6ac9fd6657f?raw)