AgentRunRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/lexifina/json-schema/lexifina-agent-run-request-schema.json",
  "title": "AgentRunRequest",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lexifina-openapi.json#/components/schemas/AgentRunRequest",
  "properties": {
    "document_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200,
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Id",
      "description": "The document the agent works on. Omit it for a conversation of its own: the agent answers, and creates or changes documents only through its tools. Continuing a conversation without document_id uses its linked document, if it has one."
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 128,
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "Session Id",
      "description": "Continue this session's conversation. Omit to start a new session; API runs never select a browser session."
    },
    "matter_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 20
        },
        {
          "type": "null"
        }
      ],
      "title": "Matter Ids",
      "description": "Matters a new conversation without a document is linked to, so the agent works within them. Only when starting one: omit session_id and document_id."
    },
    "prompt_text": {
      "type": "string",
      "maxLength": 100000,
      "minLength": 1,
      "title": "Prompt Text",
      "description": "What the agent is to do, as the user would ask it."
    },
    "source_prompt_text": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100000,
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "Source Prompt Text",
      "description": "Where the instruction came from, when it differs from prompt_text, for the record."
    },
    "change_application_mode": {
      "type": "string",
      "enum": [
        "manual",
        "automatic"
      ],
      "title": "Change Application Mode",
      "default": "manual",
      "description": "manual stages the agent's changes for a person to accept; automatic applies them when the run finishes, where the organisation allows it."
    },
    "document_version": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 1.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Version",
      "description": "Start only if the document is still at this version."
    },
    "document_content_revision": {
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0.0
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Content Revision",
      "description": "Start only if the document's content is still at this revision."
    },
    "document_content_hash": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 128,
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Content Hash",
      "description": "Start only if the document's content still has this hash."
    },
    "attachments": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/AttachmentRef"
          },
          "type": "array",
          "maxItems": 20
        },
        {
          "type": "null"
        }
      ],
      "title": "Attachments",
      "description": "Other documents the agent may read, such as a playbook or precedent. Access is checked for each."
    },
    "folder_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 5
        },
        {
          "type": "null"
        }
      ],
      "title": "Folder Ids",
      "description": "Folders the agent may search."
    },
    "reasoning_effort": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Reasoning Effort",
      "description": "How much the model reasons before answering: low, medium or high."
    },
    "page_context": {
      "anyOf": [
        {
          "$ref": "#/$defs/PageContext"
        },
        {
          "type": "null"
        }
      ],
      "description": "A page the user has open, sent with this message as context, such as the page beside a browser extension's panel."
    },
    "mode": {
      "type": "string",
      "enum": [
        "default",
        "plan"
      ],
      "title": "Mode",
      "description": "plan: the agent asks any questions, then returns a plan (result.plan) without changing the document. To carry it out, start a default-mode run with the prompt \"Implement the plan.\"",
      "default": "default"
    },
    "skill": {
      "anyOf": [
        {
          "$ref": "#/$defs/SkillRef"
        },
        {
          "type": "null"
        }
      ],
      "description": "Run a skill: the firm's standard instructions for a task."
    },
    "output_schema": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Output Schema",
      "description": "A JSON Schema (type object). The run result then carries output: JSON matching it."
    },
    "external_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 128,
          "minLength": 1
        },
        {
          "type": "null"
        }
      ],
      "title": "External Id",
      "description": "Your system's identifier for this run."
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Metadata",
      "description": "Up to 16 key-value pairs for your own use."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "prompt_text"
  ],
  "$defs": {
    "AttachmentRef": {
      "properties": {
        "document_id": {
          "type": "string",
          "maxLength": 200,
          "minLength": 1,
          "title": "Document Id"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "document_id"
      ],
      "title": "AttachmentRef"
    },
    "PageContext": {
      "properties": {
        "url": {
          "type": "string",
          "maxLength": 2000,
          "minLength": 1,
          "pattern": "^https?://",
          "title": "Url",
          "description": "The page's address."
        },
        "title": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 300
            },
            {
              "type": "null"
            }
          ],
          "title": "Title"
        },
        "kind": {
          "type": "string",
          "enum": [
            "page",
            "email",
            "pdf"
          ],
          "title": "Kind",
          "description": "pdf: only the title and address are sent; attach the file for its text.",
          "default": "page"
        },
        "text": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 40000
            },
            {
              "type": "null"
            }
          ],
          "title": "Text",
          "description": "The page's readable text."
        },
        "truncated": {
          "type": "boolean",
          "title": "Truncated",
          "description": "True when the text was cut short before it was sent.",
          "default": false
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "url"
      ],
      "title": "PageContext",
      "description": "A page the user has open, sent with the message as context: the agent reads it, and treats it as\nweb content rather than instructions. It is not shown as part of the user's message."
    },
    "SkillRef": {
      "properties": {
        "id": {
          "type": "string",
          "maxLength": 200,
          "minLength": 1,
          "title": "Id"
        },
        "version": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 64,
              "minLength": 1
            },
            {
              "type": "null"
            }
          ],
          "title": "Version",
          "description": "Run only if the skill still has this version; otherwise 409."
        },
        "variables": {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object",
          "title": "Variables",
          "description": "Values for the skill's declared arguments."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "id"
      ],
      "title": "SkillRef"
    }
  }
}