{ "schema_version": "agentpmt.docs.v1", "generated_at": "2026-07-17T10:35:16.592Z", "release_id": "29bf60dec4cba533b55ccd3d64f2f8b0eb3995cd2130786e2841eb9366a76ffc", "id": "generated-programmatic-access", "page_url": "https://www.agentpmt.com/docs/api-reference/programmatic-access", "markdown_url": "https://www.agentpmt.com/docs/api-reference/programmatic-access?format=agent-md", "json_url": "https://www.agentpmt.com/docs/api-reference/programmatic-access?format=agent-json", "source_path": "content/docs/programmatic-access.mdoc", "updated_at": "2026-04-17T20:25:58.000Z", "headings": [ { "depth": 2, "id": "trigger-autonomous-workflows-via-webhooks", "title": "Trigger Autonomous Workflows Via Webhooks" }, { "depth": 3, "id": "post-apiagent-webhooksworkflowidtrigger", "title": "POST /api/agent-webhooks/{workflowId}/trigger" }, { "depth": 3, "id": "get-apiagent-webhooksrunsrunid", "title": "GET /api/agent-webhooks/runs/{runId}" }, { "depth": 3, "id": "post-apiagent-webhooksrunsrunidcancel", "title": "POST /api/agent-webhooks/runs/{runId}/cancel" }, { "depth": 2, "id": "public", "title": "Public" }, { "depth": 3, "id": "get-health", "title": "GET /health" }, { "depth": 2, "id": "embedding", "title": "Embedding" }, { "depth": 3, "id": "get-embedjs", "title": "GET /embed.js" }, { "depth": 3, "id": "get-embedworkflowid", "title": "GET /embed/{workflowId}" }, { "depth": 3, "id": "get-embedbundlebundleid", "title": "GET /embed/bundle/{bundleId}" }, { "depth": 3, "id": "get-embedproductproductid", "title": "GET /embed/product/{productId}" } ], "related_products": [], "related_workflows": [], "doc": { "title": "Programmatic Access", "description": "Programmatic API endpoints for platform integration.", "category": "API Reference", "image": null, "full_path": "api-reference/programmatic-access", "body_markdown": "# Programmatic Access\n\n## Trigger Autonomous Workflows Via Webhooks\n\n### POST /api/agent-webhooks/{workflowId}/trigger\n\nTrigger a workflow run\n\nBase URL: `https://www.agentpmt.com`\n\n**Request Body (required)**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| prompt | string | yes | Prompt forwarded to the workflow for execution. |\n| request_id | string | no | Caller-supplied idempotency key. Retrying with the same key returns the existing run. |\n| callback_url | string | no | HTTPS URL that will receive a POST with the final run status. |\n| request_metadata | object | no | Free-form metadata persisted alongside the run for caller-side tracing. |\n\n**Example request body**\n\n```json\n{\n \"prompt\": \"Summarize the status of open orders\",\n \"request_id\": \"req_01HXXXXXXXXXXXXXXX\",\n \"callback_url\": \"https://example.com/hooks/agentpmt\",\n \"request_metadata\": {}\n}\n```\n\n**Responses**\n\n**200 — Run created or existing run returned by idempotency key.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | boolean | yes | `true` when the trigger was accepted. |\n| data | object | yes | -- |\n| run | object | yes | -- |\n| run_id | string | yes | MongoDB ObjectId of the run document. |\n| workflow_id | string | yes | ObjectId of the workflow being executed. |\n| status | \"queued\" \\| \"running\" \\| \"completed\" \\| \"failed\" \\| \"setup_required\" \\| \"cancelled\" | yes | Lifecycle status of the run.; enum: \"queued\", \"running\", \"completed\", \"failed\", \"setup_required\", \"cancelled\" |\n| created_at | string | yes | ISO-8601 timestamp when the run was created. |\n| updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |\n| cancel_requested_at | any | no | ISO-8601 timestamp when cancellation was requested. |\n| cancel_request_id | any | no | Request identifier associated with the cancellation request. |\n| cancel_reason | any | no | Bounded reason for the cancellation request. |\n| status_url | string | yes | Absolute URL the caller can poll for run status. |\n| message | string | yes | -- |\n\n**Example response**\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"run\": {\n \"run_id\": \"string\",\n \"workflow_id\": \"string\",\n \"status\": \"queued\",\n \"created_at\": \"string\",\n \"updated_at\": \"string\",\n \"cancel_requested_at\": null,\n \"cancel_request_id\": null,\n \"cancel_reason\": null\n },\n \"status_url\": \"string\"\n },\n \"message\": \"Workflow trigger accepted\"\n}\n```\n\n**202 — Idempotent replay - the existing run matching `request_id` is returned.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | boolean | yes | `true` when the trigger was accepted. |\n| data | object | yes | -- |\n| run | object | yes | -- |\n| run_id | string | yes | MongoDB ObjectId of the run document. |\n| workflow_id | string | yes | ObjectId of the workflow being executed. |\n| status | \"queued\" \\| \"running\" \\| \"completed\" \\| \"failed\" \\| \"setup_required\" \\| \"cancelled\" | yes | Lifecycle status of the run.; enum: \"queued\", \"running\", \"completed\", \"failed\", \"setup_required\", \"cancelled\" |\n| created_at | string | yes | ISO-8601 timestamp when the run was created. |\n| updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |\n| cancel_requested_at | any | no | ISO-8601 timestamp when cancellation was requested. |\n| cancel_request_id | any | no | Request identifier associated with the cancellation request. |\n| cancel_reason | any | no | Bounded reason for the cancellation request. |\n| status_url | string | yes | Absolute URL the caller can poll for run status. |\n| message | string | yes | -- |\n\n**Example response**\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"run\": {\n \"run_id\": \"string\",\n \"workflow_id\": \"string\",\n \"status\": \"queued\",\n \"created_at\": \"string\",\n \"updated_at\": \"string\",\n \"cancel_requested_at\": null,\n \"cancel_request_id\": null,\n \"cancel_reason\": null\n },\n \"status_url\": \"string\"\n },\n \"message\": \"Workflow trigger accepted\"\n}\n```\n\n**400 — Invalid workflow ID, invalid payload, or malformed request.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**401 — Missing or invalid bearer token.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**409 — Workflow is not enabled on the caller's budget and/or required credentials are missing. The response enumerates the approval request IDs created to clear the block.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | \"workflow_not_on_budget\" \\| \"missing_credentials\" \\| \"setup_required\" | yes | Stable machine-readable error code.; enum: \"workflow_not_on_budget\", \"missing_credentials\", \"setup_required\" |\n| message | string | yes | -- |\n| data | object | no | -- |\n| workflow_request_id | any | no | Approval request ID when the workflow is not yet enabled on the budget. |\n| credential_request_ids | string[] | no | Approval request IDs opened for the missing credentials. |\n| [item] | string | no | -- |\n| add_workflow | any | no | Card payload describing the workflow that needs to be added. |\n| missing_credentials | object[] | no | Requirement descriptors for credentials that still need to be configured. |\n| [item] | object | no | -- |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"workflow_not_on_budget\",\n \"message\": \"string\",\n \"data\": {\n \"workflow_request_id\": null,\n \"credential_request_ids\": [\n \"string\"\n ],\n \"add_workflow\": null,\n \"missing_credentials\": [\n {}\n ]\n }\n}\n```\n\n**500 — Unexpected server error.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**Example**\n\n**Request skeleton**\n\nReplace placeholder values before sending this request.\n\n```bash\ncurl -X POST \"https://www.agentpmt.com/api/agent-webhooks//trigger\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"prompt\": \"Summarize the status of open orders\",\n \"request_id\": \"req_01HXXXXXXXXXXXXXXX\",\n \"callback_url\": \"https://example.com/hooks/agentpmt\",\n \"request_metadata\": {}\n}'\n```\n\n### GET /api/agent-webhooks/runs/{runId}\n\nGet workflow run status\n\nBase URL: `https://www.agentpmt.com`\n\n**Responses**\n\n**200 — Current status and payload of the workflow run.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | boolean | yes | `true` when the run was located. |\n| data | object | yes | -- |\n| run | object | yes | -- |\n| run_id | string | yes | MongoDB ObjectId of the run document. |\n| workflow_id | string | yes | ObjectId of the workflow being executed. |\n| status | \"queued\" \\| \"running\" \\| \"completed\" \\| \"failed\" \\| \"setup_required\" \\| \"cancelled\" | yes | Lifecycle status of the run.; enum: \"queued\", \"running\", \"completed\", \"failed\", \"setup_required\", \"cancelled\" |\n| prompt | string | yes | Original prompt supplied when the run was triggered. |\n| response_text | any | no | Final model response text once the run completes. |\n| session_id | any | no | Chat session ID bound to this run, when available. |\n| model | any | no | Model used to execute the run, when known. |\n| error_code | any | no | Stable error code when the run failed. |\n| error_message | any | no | Human-readable error message when the run failed. |\n| callback_url | any | no | Registered callback URL, if the caller supplied one. |\n| callback_status | \"pending\" \\| \"delivered\" \\| \"failed\" \\| \"skipped\" | yes | Delivery status of the callback.; enum: \"pending\", \"delivered\", \"failed\", \"skipped\" |\n| callback_last_status | any | no | HTTP status code from the most recent callback attempt. |\n| callback_last_error | any | no | Error message from the most recent failed callback attempt. |\n| callback_attempted_at | any | no | ISO-8601 timestamp of the most recent callback attempt. |\n| callback_delivered_at | any | no | ISO-8601 timestamp when the callback was delivered successfully. |\n| request_metadata | object | no | Metadata supplied with the original trigger request. |\n| run_metadata | object | no | Internal per-run metadata captured during execution. |\n| created_at | string | yes | ISO-8601 timestamp when the run was created. |\n| updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |\n| started_at | any | no | ISO-8601 timestamp when execution began. |\n| completed_at | any | no | ISO-8601 timestamp when execution finished, if completed. |\n| cancel_requested_at | any | no | ISO-8601 timestamp when cancellation was requested. |\n| cancel_requested_by_user_id | any | no | User ObjectId that requested cancellation, when applicable. |\n| cancel_request_id | any | no | Request identifier associated with the cancellation request. |\n| cancel_reason | any | no | Bounded reason for the cancellation request. |\n\n**Example response**\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"run\": {\n \"run_id\": \"string\",\n \"workflow_id\": \"string\",\n \"status\": \"queued\",\n \"prompt\": \"string\",\n \"response_text\": null,\n \"session_id\": null,\n \"model\": null,\n \"error_code\": null,\n \"error_message\": null,\n \"callback_url\": null,\n \"callback_status\": \"pending\",\n \"callback_last_status\": null,\n \"callback_last_error\": null,\n \"callback_attempted_at\": null,\n \"callback_delivered_at\": null,\n \"request_metadata\": {},\n \"run_metadata\": {},\n \"created_at\": \"string\",\n \"updated_at\": \"string\",\n \"started_at\": null,\n \"completed_at\": null,\n \"cancel_requested_at\": null,\n \"cancel_requested_by_user_id\": null,\n \"cancel_request_id\": null,\n \"cancel_reason\": null\n }\n }\n}\n```\n\n**400 — Invalid run ID.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**401 — Missing or invalid bearer token.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**404 — Run not found for the caller.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**500 — Unexpected server error.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**Example**\n\n**Request skeleton**\n\nReplace placeholder values before sending this request.\n\n```bash\ncurl -X GET \"https://www.agentpmt.com/api/agent-webhooks/runs/\"\n```\n\n### POST /api/agent-webhooks/runs/{runId}/cancel\n\nCancel a workflow run\n\nBase URL: `https://www.agentpmt.com`\n\n**Responses**\n\n**200 — Run cancellation was accepted or the run was already cancelled.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | boolean | yes | `true` when the run was located. |\n| data | object | yes | -- |\n| run | object | yes | -- |\n| run_id | string | yes | MongoDB ObjectId of the run document. |\n| workflow_id | string | yes | ObjectId of the workflow being executed. |\n| status | \"queued\" \\| \"running\" \\| \"completed\" \\| \"failed\" \\| \"setup_required\" \\| \"cancelled\" | yes | Lifecycle status of the run.; enum: \"queued\", \"running\", \"completed\", \"failed\", \"setup_required\", \"cancelled\" |\n| prompt | string | yes | Original prompt supplied when the run was triggered. |\n| response_text | any | no | Final model response text once the run completes. |\n| session_id | any | no | Chat session ID bound to this run, when available. |\n| model | any | no | Model used to execute the run, when known. |\n| error_code | any | no | Stable error code when the run failed. |\n| error_message | any | no | Human-readable error message when the run failed. |\n| callback_url | any | no | Registered callback URL, if the caller supplied one. |\n| callback_status | \"pending\" \\| \"delivered\" \\| \"failed\" \\| \"skipped\" | yes | Delivery status of the callback.; enum: \"pending\", \"delivered\", \"failed\", \"skipped\" |\n| callback_last_status | any | no | HTTP status code from the most recent callback attempt. |\n| callback_last_error | any | no | Error message from the most recent failed callback attempt. |\n| callback_attempted_at | any | no | ISO-8601 timestamp of the most recent callback attempt. |\n| callback_delivered_at | any | no | ISO-8601 timestamp when the callback was delivered successfully. |\n| request_metadata | object | no | Metadata supplied with the original trigger request. |\n| run_metadata | object | no | Internal per-run metadata captured during execution. |\n| created_at | string | yes | ISO-8601 timestamp when the run was created. |\n| updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |\n| started_at | any | no | ISO-8601 timestamp when execution began. |\n| completed_at | any | no | ISO-8601 timestamp when execution finished, if completed. |\n| cancel_requested_at | any | no | ISO-8601 timestamp when cancellation was requested. |\n| cancel_requested_by_user_id | any | no | User ObjectId that requested cancellation, when applicable. |\n| cancel_request_id | any | no | Request identifier associated with the cancellation request. |\n| cancel_reason | any | no | Bounded reason for the cancellation request. |\n\n**Example response**\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"run\": {\n \"run_id\": \"string\",\n \"workflow_id\": \"string\",\n \"status\": \"queued\",\n \"prompt\": \"string\",\n \"response_text\": null,\n \"session_id\": null,\n \"model\": null,\n \"error_code\": null,\n \"error_message\": null,\n \"callback_url\": null,\n \"callback_status\": \"pending\",\n \"callback_last_status\": null,\n \"callback_last_error\": null,\n \"callback_attempted_at\": null,\n \"callback_delivered_at\": null,\n \"request_metadata\": {},\n \"run_metadata\": {},\n \"created_at\": \"string\",\n \"updated_at\": \"string\",\n \"started_at\": null,\n \"completed_at\": null,\n \"cancel_requested_at\": null,\n \"cancel_requested_by_user_id\": null,\n \"cancel_request_id\": null,\n \"cancel_reason\": null\n }\n }\n}\n```\n\n**400 — Invalid run ID.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**401 — Missing or invalid bearer token.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**404 — Run not found for the caller.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**409 — Run is already terminal and cannot be cancelled.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**500 — Unexpected server error.**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| success | false | yes | enum: false |\n| error | string | yes | Stable machine-readable error code. |\n| message | string | yes | Human-readable error message. |\n\n**Example response**\n\n```json\n{\n \"success\": false,\n \"error\": \"string\",\n \"message\": \"string\"\n}\n```\n\n**Example**\n\n**Request skeleton**\n\nReplace placeholder values before sending this request.\n\n```bash\ncurl -X POST \"https://www.agentpmt.com/api/agent-webhooks/runs//cancel\"\n```\n\n## Public\n\n### GET /health\n\nAPI health probe\n\nBase URL: `https://api.agentpmt.com`\n\n**Responses**\n\n**200 — Successful Response**\n\n| Field | Type | Required | Description |\n| --- | --- | --- | --- |\n| status | string | yes | Always `ok` when the API process is accepting requests. |\n\n**Example response**\n\n```json\n{\n \"status\": \"string\"\n}\n```\n\n**Example**\n\n**Request skeleton**\n\nReplace placeholder values before sending this request.\n\n```bash\ncurl -X GET \"https://api.agentpmt.com/health\"\n```\n\n## Embedding\n\n### GET /embed.js\n\nLoad the AgentPMT chat widget loader script\n\nBase URL: `https://www.agentpmt.com`\n\n**Responses**\n\n**200 — Loader script that appends the AgentPMT chat widget to the host page. Include with a standard `` tag.**\n\nReturns JavaScript source.\n\n**400 — Bad request**\n\nNo response body schema published.\n\n**401 — Unauthorized**\n\nNo response body schema published.\n\n**500 — Internal server error**\n\nNo response body schema published.\n\n**Example**\n\n**Request skeleton**\n\nReplace placeholder values before sending this request.\n\n```bash\ncurl -X GET \"https://www.agentpmt.com/embed.js\"\n```\n\n### GET /embed/{workflowId}\n\nEmbed the chat widget scoped to a workflow\n\nBase URL: `https://www.agentpmt.com`\n\n**Responses**\n\n**200 — HTML document that renders the AgentPMT chat widget inside an `