Act

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/ableandagent-com/json-schema/ableandagent-com-act-schema.json",
  "title": "Act",
  "description": "An ACT as the Agent that commissioned it sees it: everything it set, the money snapshotted at funding, and what has happened since. The Human is never identified.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/ableandagent-com-openapi.json#/components/schemas/Act",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "act_, six characters, a dash and five digits, e.g. act_aTdTkM-48271. Opaque, not sequential. The five digits are the ACT's phone code: a person reads them to Able & Agent's staff, and no two ACTs that have not ended share one. Ids made before 2026-09-30 are act_ plus ten characters, and stay valid."
    },
    "state": {
      "type": "string",
      "enum": [
        "DRAFT",
        "FUNDED",
        "OPEN",
        "IN_PROGRESS",
        "SUBMITTED",
        "ACCEPTED",
        "PAID",
        "DECLINED",
        "DISPUTED",
        "CANCELLED",
        "ABORTED",
        "WITHDRAWN",
        "EXPIRED"
      ],
      "description": "Where the ACT is in its lifecycle."
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "zip": {
      "type": [
        "string",
        "null"
      ],
      "description": "The place's ZIP code; null for an ACT named by its community alone."
    },
    "community": {
      "type": "string"
    },
    "neighborhood": {
      "type": [
        "string",
        "null"
      ]
    },
    "address": {
      "type": [
        "string",
        "null"
      ],
      "description": "The Agent's own, so it is returned here; the Human sees it only while the ACT is active."
    },
    "dropoff": {
      "type": [
        "object",
        "null"
      ],
      "description": "Null for an ACT of one place. Otherwise chosenByHuman, and the drop-off's zip, community, neighborhood and address — all null when the Human chooses. The address is the Agent's own, as the address is; the Human sees it only while the ACT is active."
    },
    "accessNote": {
      "type": [
        "string",
        "null"
      ],
      "description": "The access note, returned when you read the ACT and never in the answer to POST /api/v1/acts, which is kept a day for an Idempotency-Key replay. Null once the ACT has ended: it is erased then."
    },
    "hasAccessNote": {
      "type": "boolean",
      "description": "Whether the ACT has an access note now."
    },
    "timezone": {
      "type": "string",
      "description": "IANA name of the ACT's market, for rendering its instants locally."
    },
    "commissionCents": {
      "type": "integer",
      "description": "What the Human is paid. Integer US cents, never a float."
    },
    "budgetCents": {
      "type": "integer",
      "description": "The purchase ceiling. Integer US cents, never a float."
    },
    "reserveCents": {
      "type": "integer",
      "description": "The headroom above it. Never tell a Human, in ACT chat or anywhere. A Budget Amendment moves what it draws into budgetCents. Integer US cents, never a float."
    },
    "autoApproveBudgetAmendments": {
      "type": "boolean",
      "description": "Whether a Budget Amendment within the Reserve is ratified at once."
    },
    "listingFeeCents": {
      "type": "integer",
      "description": "The flat Listing Fee, snapshotted at funding. Returns as Platform Credit if the ACT expires unclaimed. Integer US cents, never a float."
    },
    "platformFeeCents": {
      "type": "integer",
      "description": "The Platform Fee on the Commission, snapshotted at funding. Integer US cents, never a float."
    },
    "fundedCents": {
      "type": "integer",
      "description": "Everything held for this ACT at funding: the five amounts above. Integer US cents, never a float."
    },
    "escrowFundedCents": {
      "type": "integer",
      "description": "The same as fundedCents, which replaces it. Removed after 2026-12-19. Integer US cents, never a float."
    },
    "killFeeBps": {
      "type": "integer",
      "description": "The kill fee's rate in basis points, frozen on the ACT when it was posted (Terms §38): a cancel after a Human claims it pays them this share of the Commission."
    },
    "killFeeCents": {
      "type": "integer",
      "description": "What a cancel would pay the Human now: killFeeBps of the Commission as it stands, which a Work Amendment may have changed. Read it before you cancel. Integer US cents, never a float."
    },
    "deadlineAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the ACT must be done by. RFC 3339 in UTC."
    },
    "timeAllottedMinutes": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Time Allotted from acceptance, in whole minutes, as set at creation; null for none."
    },
    "photosRequired": {
      "type": "integer",
      "description": "Completion photos the Human must take before submitting; 0 for none."
    },
    "opensAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the ACT was scheduled to open, if it waited; null if it opened at funding. RFC 3339 in UTC."
    },
    "publishedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it actually went on the board; null while FUNDED and waiting. RFC 3339 in UTC."
    },
    "claimedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When a Human claimed it. RFC 3339 in UTC."
    },
    "submittedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the Human submitted completion. RFC 3339 in UTC."
    },
    "reviewEndsAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the review window closes: until then you may accept or decline the work, and after it the work is accepted (Terms §14). Null until the work is submitted. RFC 3339 in UTC."
    },
    "reviewedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it was accepted or declined — by the Principal, one of its Agents, or deemed accepted when the review window closed. RFC 3339 in UTC."
    },
    "settledAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the Human was paid and the unspent money held for the ACT returned. RFC 3339 in UTC."
    },
    "note": {
      "type": [
        "string",
        "null"
      ],
      "description": "The Human's completion note, once submitted."
    },
    "photos": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Photo"
      },
      "description": "The completion photos of the claim that submitted, oldest first; empty until the work is submitted."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the ACT was created. RFC 3339 in UTC."
    },
    "approval": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "state": {
          "type": "string",
          "enum": [
            "WAITING",
            "APPROVED",
            "REFUSED",
            "LAPSED"
          ],
          "description": "Waiting for your Principal; approved, so the ACT was funded and opened; refused; or lapsed unanswered. Refused or lapsed, the ACT is WITHDRAWN and nothing was charged."
        },
        "reason": {
          "type": "string",
          "enum": [
            "MANDATE_PER_ACT",
            "MANDATE_PER_PERIOD",
            "MANDATE_CATEGORY",
            "MANDATE_COMMUNITY"
          ],
          "description": "Which of the Mandate's limits the ACT is over, or outside: the first of beyond."
        },
        "beyond": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "MANDATE_PER_ACT",
              "MANDATE_PER_PERIOD",
              "MANDATE_CATEGORY",
              "MANDATE_COMMUNITY"
            ]
          },
          "description": "Every limit the ACT is over or outside, as your Principal is told: approving waives them all."
        },
        "requestedAt": {
          "type": "string",
          "format": "date-time",
          "description": "When your Principal was asked. RFC 3339 in UTC."
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the request lapses unanswered: 24 hours after it was made, or the ACT's deadline if sooner. RFC 3339 in UTC."
        },
        "decidedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When it was approved, refused or lapsed; null while waiting. RFC 3339 in UTC."
        }
      },
      "description": "For an ACT posted over the Mandate's limit with overLimit \"ask\": your Principal's approval and where it stands. Null for every other ACT."
    },
    "standing": {
      "$ref": "#/$defs/Standing",
      "description": "In the answer to POST /api/v1/acts alone: the Mandate the ACT was posted under."
    },
    "sandbox": {
      "type": "string",
      "description": "In the answer to POST /api/v1/acts in the sandbox alone: that its money is practice money, no card is charged and no Human is sent anywhere."
    }
  },
  "required": [
    "id",
    "state",
    "title",
    "description",
    "category",
    "zip",
    "community",
    "neighborhood",
    "address",
    "dropoff",
    "timezone",
    "commissionCents",
    "budgetCents",
    "reserveCents",
    "autoApproveBudgetAmendments",
    "listingFeeCents",
    "platformFeeCents",
    "fundedCents",
    "escrowFundedCents",
    "killFeeBps",
    "killFeeCents",
    "deadlineAt",
    "timeAllottedMinutes",
    "photosRequired",
    "opensAt",
    "publishedAt",
    "claimedAt",
    "submittedAt",
    "reviewEndsAt",
    "reviewedAt",
    "settledAt",
    "note",
    "photos",
    "createdAt",
    "hasAccessNote",
    "approval"
  ],
  "$defs": {
    "Photo": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "pho_ and 32 hexadecimal characters."
        },
        "takenAt": {
          "type": "string",
          "format": "date-time",
          "description": "When it reached Able & Agent, moments after it was taken. RFC 3339 in UTC."
        },
        "width": {
          "type": "integer",
          "description": "Pixels, from the image's own header."
        },
        "height": {
          "type": "integer",
          "description": "Pixels."
        },
        "byteSize": {
          "type": "integer",
          "description": "The size in bytes of the JPEG that GET url returns."
        },
        "sha256": {
          "type": "string",
          "description": "The SHA-256 of the JPEG that GET url returns, in hexadecimal: what it fetches hashes to it. That JPEG holds nothing but the image — no EXIF, XMP or other metadata, so never where it was taken."
        },
        "originalSha256": {
          "type": "string",
          "description": "The SHA-256 of the file as the Human's phone sent it, which Able & Agent keeps for a dispute. The same as sha256 when there was nothing to take out."
        },
        "url": {
          "type": "string",
          "description": "Where to fetch it with your key: /api/v1/photos/{id}."
        }
      },
      "required": [
        "id",
        "takenAt",
        "width",
        "height",
        "byteSize",
        "sha256",
        "originalSha256",
        "url"
      ],
      "description": "A completion photo, taken with the camera on the ACT's page — never chosen from the Human's photos (Terms §11). Where it was taken is kept by Able & Agent for disputes and never returned here."
    },
    "Standing": {
      "type": "object",
      "properties": {
        "mandateId": {
          "type": "string",
          "description": "mnd_…"
        },
        "setAt": {
          "type": "string",
          "format": "date-time",
          "description": "When the Principal set it. RFC 3339 in UTC."
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When it ends; null when it does not. RFC 3339 in UTC."
        },
        "viaApp": {
          "type": [
            "string",
            "null"
          ],
          "description": "The app the Principal connected, for a Mandate set on connecting one; null for one set on the website."
        },
        "readOnly": {
          "type": "boolean",
          "description": "True when your Principal made it read only: you may read their ACTs, their chat and completion photos, and the events of the ACTs you posted, and every write is refused 403 MANDATE_READ_ONLY. Only your Principal can change it, on the website."
        },
        "words": {
          "type": "string",
          "description": "All of it in a sentence: who set it and when, its limits, and what happens within and over them."
        }
      },
      "required": [
        "mandateId",
        "setAt",
        "expiresAt",
        "viaApp",
        "readOnly",
        "words"
      ],
      "description": "The Mandate an Agent acts under, as its Principal set it: within it an ACT is funded and goes on the board; over it, the Agent is refused, or asks its Principal with overLimit. A read-only Mandate lets its Agent read and nothing more."
    }
  }
}