> ## Documentation Index > Fetch the complete documentation index at: https://docs.spreadjam.com/llms.txt > Use this file to discover all available pages before exploring further. # Read an action > Everything needed to do one action: its evidence (`details`, `sources`), the tracked prompts it should move (`questions`), the target page, its history and latest check, the code change Jam prepared for it (if any), and `agentPrompt`: executable instructions for your agent ending with how to report the work done. ## OpenAPI ````yaml https://api.spreadjam.com/openapi.json get /v1/actions/{actionId} openapi: 3.0.0 info: title: SpreadJam API version: 1.0.0 servers: - url: https://api.spreadjam.com security: [] tags: - name: Meta description: Identity and metadata about the authenticated key. - name: Keywords description: Keyword and topic visibility rankings. - name: API keys description: Manage the workspace's API keys. - name: Analytics description: AI-visibility analytics for the workspace. - name: Brand description: The workspace's brand profile and competitors. - name: Prompts description: Tracked GEO prompts and their cap state. - name: Visibility runs description: Run the AI-visibility scan now. - name: Credits description: The workspace's credit balance and recent charges. - name: Actions description: Recommended visibility actions and reporting them done. - name: Agent connect description: >- Sign a human up from an agent with one link, then receive an API key once they approve. No API key needed. - name: Pricing description: >- The plans an agent can choose for a human and their monthly prices. No API key needed. - name: Site changes description: >- Code changes Jam prepares for page edits and technical fixes: preview, open the pull request, discard. - name: Research description: >- The research that writes the Plan: its state, its latest report, and running it again. - name: Answers description: >- What each AI platform answered to the tracked prompts, with the sources it cited. - name: Projects description: The workspace's projects and the status of each one. - name: Billing description: The workspace's plan and the links where a person manages billing. - name: Webhooks description: >- HTTP destinations the workspace notifications are POSTed to, signed with a per-webhook secret. - name: Notifications description: >- Which notifications reach which channels (including webhooks), per event category. - name: Opportunities description: >- Article opportunities: the article pipeline behind the Plan's `new_page` actions, and requests to create content from them. - name: Planning description: Run automatic content planning now. - name: Content description: Content items, their drafts, and requests to rewrite them. - name: Revisions description: A content item's revisions. - name: Publishing description: Publishing content to destinations, now or on a schedule. - name: Deliveries description: A content item's delivery history. - name: Publications description: Where a content item is live. - name: Destinations description: Where content is published, its publishing policy, and its connection. paths: /v1/actions/{actionId}: get: tags: - Actions summary: Read an action description: >- Everything needed to do one action: its evidence (`details`, `sources`), the tracked prompts it should move (`questions`), the target page, its history and latest check, the code change Jam prepared for it (if any), and `agentPrompt`: executable instructions for your agent ending with how to report the work done. operationId: get_action parameters: - schema: type: string format: uuid example: 0b6f2c1e-6d2a-4c3e-9a1f-5e8d7c4b3a21 required: true name: actionId in: path responses: '200': description: The action. content: application/json: schema: $ref: '#/components/schemas/ActionDetail' '400': description: >- Invalid request: a parameter or body field is wrong. `details` lists each problem with what is allowed. content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: >- Missing, malformed or revoked API key (`Authorization: Bearer sk_…`). content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: No such action in this workspace. content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: >- `rate_limited` (per-key rate) or `too_many_concurrent` (expensive reads in flight); retry after `Retry-After` seconds. content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - bearerAuth: [] components: schemas: ActionDetail: allOf: - $ref: '#/components/schemas/Action' - type: object properties: kindLabel: type: string source: type: string enum: - research - planner description: >- `research`: proposed by research. `planner`: an article row the planner added. details: type: array items: type: string description: The evidence and specifics research found. sources: type: array items: type: string description: Pages research read for this action. questions: type: array items: type: object properties: promptId: type: string description: The tracked prompt (`/v1/prompts`). text: type: string nullable: true required: - promptId - text description: The tracked prompts this action should move. history: type: array items: type: object properties: id: type: string type: type: string enum: - suggested - started - sent - marked_done - delivered - verification_passed - verification_failed - dismissed - superseded - reopened - restored actor: type: string enum: - system - jam - user - agent at: type: string format: date-time url: type: string nullable: true evidence: type: string nullable: true note: type: string nullable: true required: - id - type - actor - at - url - evidence - note description: Everything that happened to the action, oldest first. check: type: object nullable: true properties: passed: type: boolean nullable: true description: Null when the check could not tell. evidence: type: string nullable: true url: type: string nullable: true at: type: string format: date-time required: - passed - evidence - url - at description: Jam's latest one-time check of a done claim. agentPrompt: type: string description: >- Executable instructions for your agent: the work, written by research, ending with how to report it done through this API (`POST /v1/actions/{id}/completion`, or `/sent` for an outreach pitch). change: $ref: '#/components/schemas/SiteChange' firstSeenAt: type: string format: date-time required: - kindLabel - source - details - sources - questions - history - check - agentPrompt - change - firstSeenAt ApiError: type: object required: - error - code properties: error: type: string description: What went wrong and how to fix the request. code: type: string description: >- Stable machine-readable code, e.g. invalid_request, unauthorized, rate_limited. requestId: type: string description: Echoes the X-Request-Id header; quote it to support. docs: type: string description: Where the error is explained. resolveUrl: type: string description: '402/403 plan errors: the dashboard page that resolves it.' details: type: array description: >- One entry per problem: path, message, and when known allowed, minimum, maximum, expected, received. items: type: object additionalProperties: true Action: type: object properties: id: type: string format: uuid kind: type: string enum: - page_edit - new_page - outreach - technical - community description: >- What the work is: `new_page` (publish a page; Jam can draft it), `page_edit` (change a page on your site; Jam can prepare the code change), `technical` (a technical fix on your site; Jam can prepare the code change), `outreach` (pitch a third-party list or page; your agent does it from `agentPrompt`), `community` (take part in a community thread; your agent does it). problem: type: string enum: - list_absent - list_low_rank - wrong_claim - page_read_rival_won - missing_page - technical_defect - engine_gap - community_absent - unclear_positioning - other description: The gap the action closes. title: type: string why: type: string impact: type: string enum: - high - medium - low rank: type: integer description: Priority within the Plan; 1 is first. targetUrl: type: string nullable: true status: type: string enum: - suggested - in_progress - sent - done - verified - unverified - dismissed - superseded description: >- The action's status, derived from its history: `suggested`: Research recommends it and nobody has acted on it yet. `in_progress`: Someone started it (POST .../start), or Jam is doing it (a draft or a code change is being prepared). `sent`: Outreach only: the pitch went out (reported by the customer or their agent, never sent by Jam). Waiting for the third party to act. `done`: Reported done, or Jam shipped it. Jam checks the page once; until that check passes the action stays done. `verified`: Jam's check found the change on the page (or the brand on the list). `unverified`: Jam's check did not find the change on the page. Fix it and POST .../checks to check again, or POST .../completion with the right URL. `dismissed`: Taken off the Plan by the customer. DELETE .../dismissal puts it back. `superseded`: A later research run no longer proposes it (the gap closed or another action replaced it). Hidden from the list unless includeSuperseded=true. opportunityId: type: string nullable: true format: uuid description: >- The article opportunity (`/v1/opportunities/{id}`) behind a `new_page` action, once Jam has one. Null otherwise. lastSeenAt: type: string format: date-time required: - id - kind - problem - title - why - impact - rank - targetUrl - status - opportunityId - lastSeenAt SiteChange: type: object nullable: true properties: id: type: string format: uuid actionId: type: string format: uuid status: type: string enum: - preparing - proposed - opening - in_review - merged - closed - failed - stale - discarded description: >- `preparing`: Jam is finding the file and writing the edit. `proposed`: ready; read `hunks`, then open the pull request or discard it. `opening`: the pull request is being opened. `in_review`: the pull request is open (`prUrl`). `merged` / `closed`: what happened to it. `failed`: Jam could not make it (`failureMessage`). `stale`: the file changed since; prepare it again. `discarded`: dropped. repository: type: string description: '`owner/name`.' baseBranch: type: string filePath: type: string nullable: true createsFile: type: boolean summary: type: string nullable: true prUrl: type: string nullable: true prNumber: type: integer nullable: true failureMessage: type: string nullable: true fallback: type: string nullable: true enum: - copy_prompt - null description: >- `copy_prompt` when Jam could not make or keep this change: hand the action's `agentPrompt` to your agent instead. hunks: type: array items: type: object properties: oldStart: type: integer oldLines: type: integer newStart: type: integer newLines: type: integer lines: type: array items: type: object properties: kind: type: string enum: - context - add - remove text: type: string required: - kind - text required: - oldStart - oldLines - newStart - newLines - lines description: The before/after preview as unified diff hunks. createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - actionId - status - repository - baseBranch - filePath - createsFile - summary - prUrl - prNumber - failureMessage - fallback - hunks - createdAt - updatedAt description: >- The latest code change Jam prepared for this action (page edits and technical fixes), with its preview. Null when none. securitySchemes: bearerAuth: type: http scheme: bearer description: >- A workspace API key issued in Settings → Developer, sent as `Bearer sk_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.