> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.usegrade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Commit a proposal

> Saves what a person confirmed: send the `proposal_token` of the assistant's `action` event, unchanged. Grade calls the SDK v1 routes the proposal stands for with your key, so each route applies its own scopes, rules and audit. A second commit of the same proposal answers the first receipt.

**Beta.** The assistant API and its reads over MCP are in beta. They are open to every
organization that pays out through Grade, and parts are not available yet, as each page says.

> [!WARNING]
>
> Sending the same token again never writes twice: a finished commit answers its first receipt. After
> `504` `COMMIT_OUTCOME_UNKNOWN` the first route may have written: check the outcome in Grade, and never
> ask the assistant for a new proposal to recover it, since a new proposal is a new write. A proposal
> can be committed for 24 hours after the assistant made it.


## OpenAPI

````yaml agent/openapi.json POST /sdk/v1/agent/commit
openapi: 3.0.3
info:
  title: Grade assistant API
  version: '1'
  description: >-
    The SDK routes of the assistant API: mint an agent token, and commit a
    proposal.
servers:
  - url: https://infra.usegrade.com/api/email
    description: Production
  - url: https://infra-sandbox.usegrade.com/api
    description: Sandbox
security:
  - applicationId: []
    apiKey: []
tags:
  - name: Assistant
paths:
  /sdk/v1/agent/commit:
    post:
      tags:
        - Assistant
      summary: Commit a proposal
      description: >-
        Saves what a person confirmed: send the `proposal_token` of the
        assistant's `action` event, unchanged. Grade calls the SDK v1 routes the
        proposal stands for with your key, so each route applies its own scopes,
        rules and audit. A second commit of the same proposal answers the first
        receipt.
      operationId: agentCommit
      requestBody:
        required: true
        description: The proposal to commit.
        content:
          application/json:
            schema:
              type: object
              required:
                - proposal_token
              additionalProperties: false
              properties:
                proposal_token:
                  type: string
                  maxLength: 65536
                  description: The `action` event's `proposal_token`.
      responses:
        '200':
          description: 'The receipt: one row per creator or post.'
          content:
            application/json:
              schema:
                type: object
                required:
                  - proposal_id
                  - action
                  - status
                  - http_status
                  - rows
                properties:
                  proposal_id:
                    type: string
                  action:
                    type: string
                  status:
                    type: string
                    enum:
                      - saved
                      - partial
                      - refused
                  http_status:
                    type: integer
                    description: The status the rows share, or 207 when they differ.
                  rows:
                    type: array
                    items:
                      type: object
                      required:
                        - key
                        - http_status
                        - status
                      properties:
                        key:
                          type: string
                          description: The id of the creator or post the row is about.
                        http_status:
                          type: integer
                          nullable: true
                        status:
                          type: string
                          enum:
                            - saved
                            - refused
                            - unknown
                            - not_sent
        '400':
          description: The proposal cannot be committed.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - code
                  - message
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                    enum:
                      - PROPOSAL_INVALID
                      - PROPOSAL_EXPIRED
                      - PROPOSAL_OTHER_AGENCY
                      - ACTION_NOT_ALLOWED
                      - ACTION_OFF
                      - SCOPE_MISSING
                      - REQUEST_NOT_ALLOWED
                      - RATE_LIMITED
                      - IDEMPOTENCY_PAYLOAD_MISMATCH
                      - IDEMPOTENCY_IN_PROGRESS
                      - IDEMPOTENCY_UNAVAILABLE
                      - AGENT_UNCONFIGURED
                      - COMMIT_UNAVAILABLE
                      - COMMIT_OUTCOME_UNKNOWN
                  message:
                    type: string
        '403':
          description: The key, the organization or the action does not allow this commit.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - code
                  - message
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                    enum:
                      - PROPOSAL_INVALID
                      - PROPOSAL_EXPIRED
                      - PROPOSAL_OTHER_AGENCY
                      - ACTION_NOT_ALLOWED
                      - ACTION_OFF
                      - SCOPE_MISSING
                      - REQUEST_NOT_ALLOWED
                      - RATE_LIMITED
                      - IDEMPOTENCY_PAYLOAD_MISMATCH
                      - IDEMPOTENCY_IN_PROGRESS
                      - IDEMPOTENCY_UNAVAILABLE
                      - AGENT_UNCONFIGURED
                      - COMMIT_UNAVAILABLE
                      - COMMIT_OUTCOME_UNKNOWN
                  message:
                    type: string
        '409':
          description: >-
            The proposal is already being committed, or was committed with
            another payload.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - code
                  - message
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                    enum:
                      - PROPOSAL_INVALID
                      - PROPOSAL_EXPIRED
                      - PROPOSAL_OTHER_AGENCY
                      - ACTION_NOT_ALLOWED
                      - ACTION_OFF
                      - SCOPE_MISSING
                      - REQUEST_NOT_ALLOWED
                      - RATE_LIMITED
                      - IDEMPOTENCY_PAYLOAD_MISMATCH
                      - IDEMPOTENCY_IN_PROGRESS
                      - IDEMPOTENCY_UNAVAILABLE
                      - AGENT_UNCONFIGURED
                      - COMMIT_UNAVAILABLE
                      - COMMIT_OUTCOME_UNKNOWN
                  message:
                    type: string
        '413':
          description: '`proposal_token` is over 65536 bytes.'
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - code
                  - message
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                    enum:
                      - PROPOSAL_INVALID
                      - PROPOSAL_EXPIRED
                      - PROPOSAL_OTHER_AGENCY
                      - ACTION_NOT_ALLOWED
                      - ACTION_OFF
                      - SCOPE_MISSING
                      - REQUEST_NOT_ALLOWED
                      - RATE_LIMITED
                      - IDEMPOTENCY_PAYLOAD_MISMATCH
                      - IDEMPOTENCY_IN_PROGRESS
                      - IDEMPOTENCY_UNAVAILABLE
                      - AGENT_UNCONFIGURED
                      - COMMIT_UNAVAILABLE
                      - COMMIT_OUTCOME_UNKNOWN
                  message:
                    type: string
        '503':
          description: Grade could not commit right now; the receipt says what was sent.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - code
                  - message
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                    enum:
                      - PROPOSAL_INVALID
                      - PROPOSAL_EXPIRED
                      - PROPOSAL_OTHER_AGENCY
                      - ACTION_NOT_ALLOWED
                      - ACTION_OFF
                      - SCOPE_MISSING
                      - REQUEST_NOT_ALLOWED
                      - RATE_LIMITED
                      - IDEMPOTENCY_PAYLOAD_MISMATCH
                      - IDEMPOTENCY_IN_PROGRESS
                      - IDEMPOTENCY_UNAVAILABLE
                      - AGENT_UNCONFIGURED
                      - COMMIT_UNAVAILABLE
                      - COMMIT_OUTCOME_UNKNOWN
                  message:
                    type: string
components:
  securitySchemes:
    applicationId:
      type: apiKey
      in: header
      name: X-Application-Id
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.