# Programmatic Access

> Programmatic API endpoints for platform integration.

Content type: documentation
Source URL: https://www.agentpmt.com/docs/api-reference/programmatic-access
Markdown URL: https://www.agentpmt.com/docs/api-reference/programmatic-access?format=agent-md
Category: API Reference

---

# Programmatic Access

## Trigger Autonomous Workflows Via Webhooks

### POST /api/agent-webhooks/{workflowId}/trigger

Trigger a workflow run

Base URL: `https://www.agentpmt.com`

**Request Body (required)**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| prompt | string | yes | Prompt forwarded to the workflow for execution. |
| request_id | string | no | Caller-supplied idempotency key. Retrying with the same key returns the existing run. |
| callback_url | string | no | HTTPS URL that will receive a POST with the final run status. |
| request_metadata | object | no | Free-form metadata persisted alongside the run for caller-side tracing. |

**Example request body**

```json
{
  "prompt": "Summarize the status of open orders",
  "request_id": "req_01HXXXXXXXXXXXXXXX",
  "callback_url": "https://example.com/hooks/agentpmt",
  "request_metadata": {}
}
```

**Responses**

**200 — Run created or existing run returned by idempotency key.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | boolean | yes | `true` when the trigger was accepted. |
| data | object | yes | -- |
| run | object | yes | -- |
| run_id | string | yes | MongoDB ObjectId of the run document. |
| workflow_id | string | yes | ObjectId of the workflow being executed. |
| status | "queued" \| "running" \| "completed" \| "failed" \| "setup_required" \| "cancelled" | yes | Lifecycle status of the run.; enum: "queued", "running", "completed", "failed", "setup_required", "cancelled" |
| created_at | string | yes | ISO-8601 timestamp when the run was created. |
| updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |
| cancel_requested_at | any | no | ISO-8601 timestamp when cancellation was requested. |
| cancel_request_id | any | no | Request identifier associated with the cancellation request. |
| cancel_reason | any | no | Bounded reason for the cancellation request. |
| status_url | string | yes | Absolute URL the caller can poll for run status. |
| message | string | yes | -- |

**Example response**

```json
{
  "success": true,
  "data": {
    "run": {
      "run_id": "string",
      "workflow_id": "string",
      "status": "queued",
      "created_at": "string",
      "updated_at": "string",
      "cancel_requested_at": null,
      "cancel_request_id": null,
      "cancel_reason": null
    },
    "status_url": "string"
  },
  "message": "Workflow trigger accepted"
}
```

**202 — Idempotent replay - the existing run matching `request_id` is returned.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | boolean | yes | `true` when the trigger was accepted. |
| data | object | yes | -- |
| run | object | yes | -- |
| run_id | string | yes | MongoDB ObjectId of the run document. |
| workflow_id | string | yes | ObjectId of the workflow being executed. |
| status | "queued" \| "running" \| "completed" \| "failed" \| "setup_required" \| "cancelled" | yes | Lifecycle status of the run.; enum: "queued", "running", "completed", "failed", "setup_required", "cancelled" |
| created_at | string | yes | ISO-8601 timestamp when the run was created. |
| updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |
| cancel_requested_at | any | no | ISO-8601 timestamp when cancellation was requested. |
| cancel_request_id | any | no | Request identifier associated with the cancellation request. |
| cancel_reason | any | no | Bounded reason for the cancellation request. |
| status_url | string | yes | Absolute URL the caller can poll for run status. |
| message | string | yes | -- |

**Example response**

```json
{
  "success": true,
  "data": {
    "run": {
      "run_id": "string",
      "workflow_id": "string",
      "status": "queued",
      "created_at": "string",
      "updated_at": "string",
      "cancel_requested_at": null,
      "cancel_request_id": null,
      "cancel_reason": null
    },
    "status_url": "string"
  },
  "message": "Workflow trigger accepted"
}
```

**400 — Invalid workflow ID, invalid payload, or malformed request.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**401 — Missing or invalid bearer token.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**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.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | "workflow_not_on_budget" \| "missing_credentials" \| "setup_required" | yes | Stable machine-readable error code.; enum: "workflow_not_on_budget", "missing_credentials", "setup_required" |
| message | string | yes | -- |
| data | object | no | -- |
| workflow_request_id | any | no | Approval request ID when the workflow is not yet enabled on the budget. |
| credential_request_ids | string[] | no | Approval request IDs opened for the missing credentials. |
| [item] | string | no | -- |
| add_workflow | any | no | Card payload describing the workflow that needs to be added. |
| missing_credentials | object[] | no | Requirement descriptors for credentials that still need to be configured. |
| [item] | object | no | -- |

**Example response**

```json
{
  "success": false,
  "error": "workflow_not_on_budget",
  "message": "string",
  "data": {
    "workflow_request_id": null,
    "credential_request_ids": [
      "string"
    ],
    "add_workflow": null,
    "missing_credentials": [
      {}
    ]
  }
}
```

**500 — Unexpected server error.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**Example**

**Request skeleton**

Replace placeholder values before sending this request.

```bash
curl -X POST "https://www.agentpmt.com/api/agent-webhooks/<workflowId>/trigger" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Summarize the status of open orders",
  "request_id": "req_01HXXXXXXXXXXXXXXX",
  "callback_url": "https://example.com/hooks/agentpmt",
  "request_metadata": {}
}'
```

### GET /api/agent-webhooks/runs/{runId}

Get workflow run status

Base URL: `https://www.agentpmt.com`

**Responses**

**200 — Current status and payload of the workflow run.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | boolean | yes | `true` when the run was located. |
| data | object | yes | -- |
| run | object | yes | -- |
| run_id | string | yes | MongoDB ObjectId of the run document. |
| workflow_id | string | yes | ObjectId of the workflow being executed. |
| status | "queued" \| "running" \| "completed" \| "failed" \| "setup_required" \| "cancelled" | yes | Lifecycle status of the run.; enum: "queued", "running", "completed", "failed", "setup_required", "cancelled" |
| prompt | string | yes | Original prompt supplied when the run was triggered. |
| response_text | any | no | Final model response text once the run completes. |
| session_id | any | no | Chat session ID bound to this run, when available. |
| model | any | no | Model used to execute the run, when known. |
| error_code | any | no | Stable error code when the run failed. |
| error_message | any | no | Human-readable error message when the run failed. |
| callback_url | any | no | Registered callback URL, if the caller supplied one. |
| callback_status | "pending" \| "delivered" \| "failed" \| "skipped" | yes | Delivery status of the callback.; enum: "pending", "delivered", "failed", "skipped" |
| callback_last_status | any | no | HTTP status code from the most recent callback attempt. |
| callback_last_error | any | no | Error message from the most recent failed callback attempt. |
| callback_attempted_at | any | no | ISO-8601 timestamp of the most recent callback attempt. |
| callback_delivered_at | any | no | ISO-8601 timestamp when the callback was delivered successfully. |
| request_metadata | object | no | Metadata supplied with the original trigger request. |
| run_metadata | object | no | Internal per-run metadata captured during execution. |
| created_at | string | yes | ISO-8601 timestamp when the run was created. |
| updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |
| started_at | any | no | ISO-8601 timestamp when execution began. |
| completed_at | any | no | ISO-8601 timestamp when execution finished, if completed. |
| cancel_requested_at | any | no | ISO-8601 timestamp when cancellation was requested. |
| cancel_requested_by_user_id | any | no | User ObjectId that requested cancellation, when applicable. |
| cancel_request_id | any | no | Request identifier associated with the cancellation request. |
| cancel_reason | any | no | Bounded reason for the cancellation request. |

**Example response**

```json
{
  "success": true,
  "data": {
    "run": {
      "run_id": "string",
      "workflow_id": "string",
      "status": "queued",
      "prompt": "string",
      "response_text": null,
      "session_id": null,
      "model": null,
      "error_code": null,
      "error_message": null,
      "callback_url": null,
      "callback_status": "pending",
      "callback_last_status": null,
      "callback_last_error": null,
      "callback_attempted_at": null,
      "callback_delivered_at": null,
      "request_metadata": {},
      "run_metadata": {},
      "created_at": "string",
      "updated_at": "string",
      "started_at": null,
      "completed_at": null,
      "cancel_requested_at": null,
      "cancel_requested_by_user_id": null,
      "cancel_request_id": null,
      "cancel_reason": null
    }
  }
}
```

**400 — Invalid run ID.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**401 — Missing or invalid bearer token.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**404 — Run not found for the caller.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**500 — Unexpected server error.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**Example**

**Request skeleton**

Replace placeholder values before sending this request.

```bash
curl -X GET "https://www.agentpmt.com/api/agent-webhooks/runs/<runId>"
```

### POST /api/agent-webhooks/runs/{runId}/cancel

Cancel a workflow run

Base URL: `https://www.agentpmt.com`

**Responses**

**200 — Run cancellation was accepted or the run was already cancelled.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | boolean | yes | `true` when the run was located. |
| data | object | yes | -- |
| run | object | yes | -- |
| run_id | string | yes | MongoDB ObjectId of the run document. |
| workflow_id | string | yes | ObjectId of the workflow being executed. |
| status | "queued" \| "running" \| "completed" \| "failed" \| "setup_required" \| "cancelled" | yes | Lifecycle status of the run.; enum: "queued", "running", "completed", "failed", "setup_required", "cancelled" |
| prompt | string | yes | Original prompt supplied when the run was triggered. |
| response_text | any | no | Final model response text once the run completes. |
| session_id | any | no | Chat session ID bound to this run, when available. |
| model | any | no | Model used to execute the run, when known. |
| error_code | any | no | Stable error code when the run failed. |
| error_message | any | no | Human-readable error message when the run failed. |
| callback_url | any | no | Registered callback URL, if the caller supplied one. |
| callback_status | "pending" \| "delivered" \| "failed" \| "skipped" | yes | Delivery status of the callback.; enum: "pending", "delivered", "failed", "skipped" |
| callback_last_status | any | no | HTTP status code from the most recent callback attempt. |
| callback_last_error | any | no | Error message from the most recent failed callback attempt. |
| callback_attempted_at | any | no | ISO-8601 timestamp of the most recent callback attempt. |
| callback_delivered_at | any | no | ISO-8601 timestamp when the callback was delivered successfully. |
| request_metadata | object | no | Metadata supplied with the original trigger request. |
| run_metadata | object | no | Internal per-run metadata captured during execution. |
| created_at | string | yes | ISO-8601 timestamp when the run was created. |
| updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |
| started_at | any | no | ISO-8601 timestamp when execution began. |
| completed_at | any | no | ISO-8601 timestamp when execution finished, if completed. |
| cancel_requested_at | any | no | ISO-8601 timestamp when cancellation was requested. |
| cancel_requested_by_user_id | any | no | User ObjectId that requested cancellation, when applicable. |
| cancel_request_id | any | no | Request identifier associated with the cancellation request. |
| cancel_reason | any | no | Bounded reason for the cancellation request. |

**Example response**

```json
{
  "success": true,
  "data": {
    "run": {
      "run_id": "string",
      "workflow_id": "string",
      "status": "queued",
      "prompt": "string",
      "response_text": null,
      "session_id": null,
      "model": null,
      "error_code": null,
      "error_message": null,
      "callback_url": null,
      "callback_status": "pending",
      "callback_last_status": null,
      "callback_last_error": null,
      "callback_attempted_at": null,
      "callback_delivered_at": null,
      "request_metadata": {},
      "run_metadata": {},
      "created_at": "string",
      "updated_at": "string",
      "started_at": null,
      "completed_at": null,
      "cancel_requested_at": null,
      "cancel_requested_by_user_id": null,
      "cancel_request_id": null,
      "cancel_reason": null
    }
  }
}
```

**400 — Invalid run ID.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**401 — Missing or invalid bearer token.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**404 — Run not found for the caller.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**409 — Run is already terminal and cannot be cancelled.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**500 — Unexpected server error.**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| success | false | yes | enum: false |
| error | string | yes | Stable machine-readable error code. |
| message | string | yes | Human-readable error message. |

**Example response**

```json
{
  "success": false,
  "error": "string",
  "message": "string"
}
```

**Example**

**Request skeleton**

Replace placeholder values before sending this request.

```bash
curl -X POST "https://www.agentpmt.com/api/agent-webhooks/runs/<runId>/cancel"
```

## Public

### GET /health

API health probe

Base URL: `https://api.agentpmt.com`

**Responses**

**200 — Successful Response**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| status | string | yes | Always `ok` when the API process is accepting requests. |

**Example response**

```json
{
  "status": "string"
}
```

**Example**

**Request skeleton**

Replace placeholder values before sending this request.

```bash
curl -X GET "https://api.agentpmt.com/health"
```

## Embedding

### GET /embed.js

Load the AgentPMT chat widget loader script

Base URL: `https://www.agentpmt.com`

**Responses**

**200 — Loader script that appends the AgentPMT chat widget to the host page. Include with a standard `<script src="/embed.js" async></script>` tag.**

Returns JavaScript source.

**400 — Bad request**

No response body schema published.

**401 — Unauthorized**

No response body schema published.

**500 — Internal server error**

No response body schema published.

**Example**

**Request skeleton**

Replace placeholder values before sending this request.

```bash
curl -X GET "https://www.agentpmt.com/embed.js"
```

### GET /embed/{workflowId}

Embed the chat widget scoped to a workflow

Base URL: `https://www.agentpmt.com`

**Responses**

**200 — HTML document that renders the AgentPMT chat widget inside an `<iframe>`. End users sign in with their own AgentPMT credentials.**

Returns HTML document.

**400 — Bad request**

No response body schema published.

**401 — Unauthorized**

No response body schema published.

**404 — The referenced tool, bundle, or workflow was not found.**

Returns HTML document.

**500 — Internal server error**

No response body schema published.

**Example**

**Request skeleton**

Replace placeholder values before sending this request.

```bash
curl -X GET "https://www.agentpmt.com/embed/<workflowId>"
```

### GET /embed/bundle/{bundleId}

Embed the chat widget scoped to a bundle of tools and workflows

Base URL: `https://www.agentpmt.com`

**Responses**

**200 — HTML document that renders the AgentPMT chat widget inside an `<iframe>`. End users sign in with their own AgentPMT credentials.**

Returns HTML document.

**400 — Bad request**

No response body schema published.

**401 — Unauthorized**

No response body schema published.

**404 — The referenced tool, bundle, or workflow was not found.**

Returns HTML document.

**500 — Internal server error**

No response body schema published.

**Example**

**Request skeleton**

Replace placeholder values before sending this request.

```bash
curl -X GET "https://www.agentpmt.com/embed/bundle/<bundleId>"
```

### GET /embed/product/{productId}

Embed the chat widget scoped to a single product tool

Base URL: `https://www.agentpmt.com`

**Responses**

**200 — HTML document that renders the AgentPMT chat widget inside an `<iframe>`. End users sign in with their own AgentPMT credentials.**

Returns HTML document.

**400 — Bad request**

No response body schema published.

**401 — Unauthorized**

No response body schema published.

**404 — The referenced tool, bundle, or workflow was not found.**

Returns HTML document.

**500 — Internal server error**

No response body schema published.

**Example**

**Request skeleton**

Replace placeholder values before sending this request.

```bash
curl -X GET "https://www.agentpmt.com/embed/product/<productId>"
```