RunEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bowmark-ai/json-schema/bowmark-ai-run-envelope-schema.json",
  "title": "RunEnvelope",
  "description": "What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/bowmark-ai-openapi.json#/components/schemas/RunEnvelope",
  "type": "object",
  "required": [
    "ok",
    "status",
    "result",
    "logs",
    "error",
    "ms"
  ],
  "properties": {
    "runId": {
      "type": "string",
      "description": "Stable id for this run. Quote it in a support or `report` message."
    },
    "ok": {
      "type": "boolean",
      "description": "False only when the run produced nothing usable."
    },
    "status": {
      "type": "string",
      "enum": [
        "ok",
        "error",
        "partial",
        "needs_user"
      ],
      "description": "`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."
    },
    "egress": {
      "type": "string",
      "enum": [
        "default",
        "link"
      ],
      "description": "The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Link)."
    },
    "result": {
      "description": "Whatever the script `return`ed. Any JSON value."
    },
    "logs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Lines the script wrote with `log(...)`."
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why the run failed, in plain words. Null on success."
    },
    "ms": {
      "type": "integer",
      "description": "How long the script itself ran, in milliseconds."
    },
    "queuedMs": {
      "type": "integer",
      "description": "How long the run waited for a worker before starting. Present only when it was a second or more."
    },
    "needs": {
      "type": "array",
      "description": "The sign-ins this script is waiting on. Present when `status` is `needs_user`.",
      "items": {
        "type": "object",
        "required": [
          "capability",
          "provider",
          "providerTitle",
          "kind"
        ],
        "properties": {
          "capability": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "providerTitle": {
            "type": "string",
            "description": "The site's name, to show a person."
          },
          "kind": {
            "type": "string"
          }
        }
      }
    },
    "incomplete": {
      "type": "object",
      "description": "Present only when `status` is `partial`: which calls did not answer.",
      "properties": {
        "summary": {
          "type": "string"
        },
        "totalCalls": {
          "type": "integer"
        }
      },
      "additionalProperties": true
    },
    "emptyHanded": {
      "type": "object",
      "description": "Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.",
      "additionalProperties": true
    },
    "notes": {
      "type": "array",
      "description": "Caveats a call attached to a complete answer. Never changes `status`.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "properties": {
        "handoff": {
          "type": "object",
          "description": "A single-use sign-in link for a person to open. Expires at `expiresAt`.",
          "properties": {
            "ref": {
              "type": "string"
            },
            "url": {
              "type": "string",
              "format": "uri"
            },
            "expiresAt": {
              "type": "string",
              "format": "date-time"
            }
          }
        },
        "concurrency": {
          "type": "object",
          "description": "On a 429: how many runs are in flight and when to retry.",
          "properties": {
            "limit": {
              "type": "integer"
            },
            "inFlight": {
              "type": "integer"
            },
            "retryAfterSeconds": {
              "type": "integer"
            }
          }
        }
      },
      "additionalProperties": true
    },
    "notice": {
      "type": "object",
      "description": "Set when the account owner has not accepted the current Terms. Relay it to them.",
      "additionalProperties": true
    }
  }
}