# 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

---

## Tool Calls Via REST API

### GET /credits/balance

Get My Credit Balance

Check credit balance.

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

Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| Authorization (header) | string | yes | -- |

Responses

#### 200 - Current available credit balance and next expiration.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | CustomerCreditBalanceResponse | no | -- |
| (body).success | boolean | no | `true` when the balance lookup succeeded. |
| (body).message | string | no | Human-readable status message. |
| (body).data | CustomerCreditBalanceData | yes | -- |
| (body).data.balance | integer | yes | Current available credit balance, in whole credits (100 credits = $1). |
| (body).data.expiration | string | no | ISO-8601 timestamp of the next credit expiration, or null when the balance is zero. |
| (body).data.expires_in_days | integer | no | Whole days until the next expiration, or null when the balance is zero. |

Example

```json
{
  "success": true,
  "message": "string",
  "data": {
    "balance": 0,
    "expiration": "string",
    "expires_in_days": 0
  }
}
```

#### 422 - Validation Error
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | HTTPValidationError | no | -- |
| (body).detail | ValidationError[] | no | -- |
| (body).detail[] | ValidationError | no | -- |
| (body).detail[].loc | string[] | yes | -- |
| (body).detail[].loc[] | string | no | -- |
| (body).detail[].msg | string | yes | -- |
| (body).detail[].type | string | yes | -- |
| (body).detail[].input | any | no | -- |
| (body).detail[].ctx | object | no | -- |

Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

Example

#### Request skeleton

Replace placeholder values before sending this request.

```bash
curl -X GET "https://api.agentpmt.com/credits/balance" \
  -H "Authorization: "
```

### GET /credits/history

Get My Credit History

View credit transaction history.

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

Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| limit (query) | integer | no | -- |
| Authorization (header) | string | yes | -- |

Responses

#### 200 - Credit grants and transaction audit trail for the caller.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | CustomerCreditHistoryResponse | no | -- |
| (body).success | boolean | no | `true` when the history lookup succeeded. |
| (body).message | string | no | Human-readable status message. |
| (body).data | CustomerCreditHistoryData | yes | -- |
| (body).data.grants | CustomerCreditGrant[] | yes | Credit grants owned by the caller, newest first. |
| (body).data.grants[] | CustomerCreditGrant | no | -- |
| (body).data.grants[]._id | string | yes | Grant document ID (serialized as `_id` in the response). |
| (body).data.grants[].user_id | string | yes | Owning user ID. |
| (body).data.grants[].amount_credits | integer | yes | Credits originally granted (positive integer). |
| (body).data.grants[].amount_usd | number | yes | USD equivalent of the grant at issuance. |
| (body).data.grants[].remaining_credits | integer | yes | Credits still available from this grant. |
| (body).data.grants[].credit_type | string | yes | Grant source classification (for example `admin_grant`, `referral_signup`, `x402_purchase`). |
| (body).data.grants[].source_metadata | object | no | Free-form metadata supplied when the grant was created. |
| (body).data.grants[].date_created | string | yes | ISO-8601 timestamp the grant was issued. |
| (body).data.grants[].pooled_at | string | no | ISO-8601 timestamp the grant was added to the pool. |
| (body).data.grants[].expires_at | string | no | ISO-8601 timestamp the grant expires. |
| (body).data.transactions | CustomerCreditTransaction[] | yes | Transaction audit trail, newest first. |
| (body).data.transactions[] | CustomerCreditTransaction | no | -- |
| (body).data.transactions[]._id | string | yes | Transaction document ID (serialized as `_id` in the response). |
| (body).data.transactions[].user_id | string | yes | Owning user ID. |
| (body).data.transactions[].transaction_type | string | yes | One of `grant`, `expiration`, `revocation`, or `purchase` (tool deduction). |
| (body).data.transactions[].amount_credits | integer | yes | Credits applied by this transaction. Negative for debits (expiration/revocation/purchase), positive for grants. |
| (body).data.transactions[].amount_usd | number | yes | USD equivalent of the transaction. |
| (body).data.transactions[].balance_after_credits | integer | yes | Balance in credits after applying the transaction. |
| (body).data.transactions[].balance_after_usd | number | yes | Balance in USD after applying the transaction. |
| (body).data.transactions[].date_created | string | yes | ISO-8601 timestamp of the transaction. |

Example

```json
{
  "success": true,
  "message": "string",
  "data": {
    "grants": [
      {
        "_id": "string",
        "user_id": "string",
        "amount_credits": 0,
        "amount_usd": 0,
        "remaining_credits": 0,
        "credit_type": "string",
        "source_metadata": {},
        "date_created": "string",
        "pooled_at": "string",
        "expires_at": "string"
      }
    ],
    "transactions": [
      {
        "_id": "string",
        "user_id": "string",
        "transaction_type": "string",
        "amount_credits": 0,
        "amount_usd": 0,
        "balance_after_credits": 0,
        "balance_after_usd": 0,
        "date_created": "string"
      }
    ]
  }
}
```

#### 422 - Validation Error
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | HTTPValidationError | no | -- |
| (body).detail | ValidationError[] | no | -- |
| (body).detail[] | ValidationError | no | -- |
| (body).detail[].loc | string[] | yes | -- |
| (body).detail[].loc[] | string | no | -- |
| (body).detail[].msg | string | yes | -- |
| (body).detail[].type | string | yes | -- |
| (body).detail[].input | any | no | -- |
| (body).detail[].ctx | object | no | -- |

Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

Example

#### Request skeleton

Replace placeholder values before sending this request.

```bash
curl -X GET "https://api.agentpmt.com/credits/history?limit=<limit>" \
  -H "Authorization: "
```

### POST /issues/report

Report an issue with a tool call

Report an issue with a tool call.

Args:
    request: FastAPI Request object.
    issue_data: Issue report data (product_id, error_message, recommended_improvements).
    authorization: Authorization Bearer token.
    x_instance_id: Optional connection instance ID (x-instance-id header).

Returns:
    Success response with created issue ID.

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

Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| Authorization (header) | string | yes | Bearer access token |
| x-instance-id (header) | string | no | Connection instance ID for persistent storage |

Request Body (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | IssueReportRequest | no | Request model for reporting tool usage errors |
| (body).product_id | string | yes | -- |
| (body).error_message | string | yes | -- |
| (body).recommended_improvements | string | no | -- |

Example

```json
{
  "product_id": "string",
  "error_message": "string",
  "recommended_improvements": "string"
}
```

Responses

#### 200 - The issue report was recorded. The endpoint always reports success (even when the product identifier could not be resolved) to avoid blocking agent flows.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | IssueReportResponse | no | -- |
| (body).success | boolean | no | `true` when the issue report was accepted. |
| (body).message | string | no | Human-readable status message. |
| (body).data | IssueReportData | yes | -- |
| (body).data.issue_id | string | yes | ID of the issue document that was created. |
| (body).data.product_found | boolean | yes | True when the reported product identifier resolved to a known product; false when the issue was still recorded against the raw identifier the caller supplied. |
| (body).data.lookup_method | string | yes | How the product identifier was resolved (for example `object_id`, `slug`, `exact_name`, or `not_found`). |
| (body).data.product_id | string | yes | Original product identifier the caller supplied. |
| (body).data.product_name | string | no | Canonical product name, when the identifier resolved. |
| (body).data.status | string | yes | Issue status after creation. Reports are always opened in `open`. |

Example

```json
{
  "success": true,
  "message": "string",
  "data": {
    "issue_id": "string",
    "product_found": true,
    "lookup_method": "string",
    "product_id": "string",
    "product_name": "string",
    "status": "string"
  }
}
```

#### 422 - Validation Error
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | HTTPValidationError | no | -- |
| (body).detail | ValidationError[] | no | -- |
| (body).detail[] | ValidationError | no | -- |
| (body).detail[].loc | string[] | yes | -- |
| (body).detail[].loc[] | string | no | -- |
| (body).detail[].msg | string | yes | -- |
| (body).detail[].type | string | yes | -- |
| (body).detail[].input | any | no | -- |
| (body).detail[].ctx | object | no | -- |

Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

Example

#### Request skeleton

Replace placeholder values before sending this request.

```bash
curl -X POST "https://api.agentpmt.com/issues/report" \
  -H "Authorization: " \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "string",
  "error_message": "string",
  "recommended_improvements": "string"
}'
```

### GET /products/fetch

List tools available in your budget

List tools available in your budget.

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

Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| page (query) | integer | no | Page number (1-based) |
| page_size (query) | integer | no | Items per page (max 100) |
| Authorization (header) | string | yes | Bearer access token |
| X-Page (header) | integer | no | Page number from header (alternative to query param) |
| X-Page-Size (header) | integer | no | Page size from header (alternative to query param) |
| x-instance-id (header) | string | no | Connection instance ID for persistent storage |
| x-instance-metadata (header) | string | no | Instance metadata as JSON string |

Responses

#### 200 - Paginated list of tools available to the caller, plus a pre-prompt and a sample tool-call curl.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | ProductsFetchResponse | no | -- |
| (body).success | boolean | no | `true` when the catalog was fetched successfully. |
| (body).instance_id | string | no | Connection instance ID the caller can persist and echo back via the `x-instance-id` header on subsequent calls to keep per-session context. |
| (body).details | ProductsFetchDetails | yes | -- |
| (body).details.tools_on_this_page | integer | yes | Number of tools included in this page of results. |
| (body).details.total_qualified_tools | integer | yes | Total number of tools accessible to the caller (across all pages). |
| (body).details.page_returned | integer | yes | Page index returned (1-based). |
| (body).details.page_size_requested | integer | yes | Requested page size. |
| (body).details.page_source | string | yes | `header` when the caller supplied `X-Page`; `query` otherwise. |
| (body).details.page_size_source | string | yes | `header` when the caller supplied `X-Page-Size`; `query` otherwise. |
| (body).details.total_pages | integer | yes | Total number of pages available. |
| (body).details.has_next_page | boolean | yes | True when another page exists after this one. |
| (body).details.has_previous_page | boolean | yes | True when a page exists before this one. |
| (body).preprompt | string | yes | Human-readable preamble generated for downstream LLM callers. Changes based on whether any tools matched. |
| (body).tools | ProductsFetchTool[] | yes | Tools available to the caller on this page. |
| (body).tools[] | ProductsFetchTool | no | Loose representation of a tool/product entry returned by /products/fetch.

The full tool schema is product-specific; only the identifier, display
label, and action metadata are stable across the catalog. Additional
product-declared fields are passed through unchanged. |
| (body).tools[].product_id | string | no | Tool ObjectId as a string. |
| (body).tools[].name | string | no | Tool function name used when invoking the tool. |
| (body).tools[].display_name | string | no | Human-readable product name. |
| (body).tools[].description | string | no | Short description of what the tool does. |
| (body).pagination | ProductsFetchPagination | yes | Canonical pagination descriptor (matches the `details` block). |
| (body).pagination.page | integer | yes | Page index returned (1-based). |
| (body).pagination.page_size | integer | yes | Page size used to compute this response. |
| (body).pagination.total_count | integer | yes | Total number of items across all pages. |
| (body).pagination.total_pages | integer | yes | Total number of pages available. |
| (body).pagination.has_next | boolean | yes | True when another page exists after this one. |
| (body).pagination.has_prev | boolean | yes | True when a page exists before this one. |
| (body).example_tool_call | string | no | Illustrative curl command showing how to invoke one of the returned tools. |

Example

```json
{
  "success": true,
  "instance_id": "string",
  "details": {
    "tools_on_this_page": 0,
    "total_qualified_tools": 0,
    "page_returned": 0,
    "page_size_requested": 0,
    "page_source": "string",
    "page_size_source": "string",
    "total_pages": 0,
    "has_next_page": true,
    "has_previous_page": true
  },
  "preprompt": "string",
  "tools": [
    {
      "product_id": "string",
      "name": "string",
      "display_name": "string",
      "description": "string"
    }
  ],
  "pagination": {
    "page": 0,
    "page_size": 0,
    "total_count": 0,
    "total_pages": 0,
    "has_next": true,
    "has_prev": true
  },
  "example_tool_call": "string"
}
```

#### 422 - Validation Error
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | HTTPValidationError | no | -- |
| (body).detail | ValidationError[] | no | -- |
| (body).detail[] | ValidationError | no | -- |
| (body).detail[].loc | string[] | yes | -- |
| (body).detail[].loc[] | string | no | -- |
| (body).detail[].msg | string | yes | -- |
| (body).detail[].type | string | yes | -- |
| (body).detail[].input | any | no | -- |
| (body).detail[].ctx | object | no | -- |

Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

Example

#### Request skeleton

Replace placeholder values before sending this request.

```bash
curl -X GET "https://api.agentpmt.com/products/fetch?page=<page>&page_size=<page_size>" \
  -H "Authorization: "
```

### POST /products/purchase

Purchase Products Endpoint

Purchase and invoke a tool.

Returns:
    Product call response with order confirmation and instance_id for connection tracking.

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

Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| Authorization (header) | string | yes | Bearer access token |
| x-instance-id (header) | string | no | Connection instance ID for persistent storage |
| x-instance-metadata (header) | string | no | Instance metadata as JSON string (AI agent info) |

Request Body (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | Purchase-and-invoke request envelope. The `parameters` field is tool-specific; retrieve the declared action schema from `GET /products/fetch` or the product's marketplace page. |
| (body).product_id | string | yes | The ID of the tool (product) to purchase and invoke. |
| (body).parameters | object | no | Action-specific parameters. The shape depends on the product's declared action schema. |

Example

```json
{
  "product_id": "<product_id>",
  "parameters": {
    "action": "<action_name>",
    "example_param": "value"
  }
}
```

Responses

#### 200 - Tool invocation result along with an `instance_id` that the caller can persist for follow-up calls to the same connection.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | boolean | no | -- |
| (body).data | object | no | Tool-specific response payload returned by the product. |
| (body).order_id | string | no | Identifier for the purchase/order that was created. |
| (body).instance_id | string | no | Connection instance the caller can pass back via `x-instance-id` to persist state across calls. |

Example

```json
{
  "success": true,
  "data": {
    "result": "value"
  },
  "order_id": "ord_01HXXXXXXXXXXXXXXX",
  "instance_id": "inst_01HXXXXXXXXXXXXXXX"
}
```

#### 422 - Validation Error
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | HTTPValidationError | no | -- |
| (body).detail | ValidationError[] | no | -- |
| (body).detail[] | ValidationError | no | -- |
| (body).detail[].loc | string[] | yes | -- |
| (body).detail[].loc[] | string | no | -- |
| (body).detail[].msg | string | yes | -- |
| (body).detail[].type | string | yes | -- |
| (body).detail[].input | any | no | -- |
| (body).detail[].ctx | object | no | -- |

Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

Example

#### Request skeleton

Replace placeholder values before sending this request.

```bash
curl -X POST "https://api.agentpmt.com/products/purchase" \
  -H "Authorization: " \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "<product_id>",
  "parameters": {
    "action": "<action_name>",
    "example_param": "value"
  }
}'
```

## 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 |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).prompt | string | yes | Prompt forwarded to the workflow for execution. |
| (body).request_id | string | no | Caller-supplied idempotency key. Retrying with the same key returns the existing run. |
| (body).callback_url | string | no | HTTPS URL that will receive a POST with the final run status. |
| (body).request_metadata | object | no | Free-form metadata persisted alongside the run for caller-side tracing. |

Example

```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.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | boolean | yes | `true` when the trigger was accepted. |
| (body).data | object | yes | -- |
| (body).data.run | object | yes | -- |
| (body).data.run.run_id | string | yes | MongoDB ObjectId of the run document. |
| (body).data.run.workflow_id | string | yes | ObjectId of the workflow being executed. |
| (body).data.run.status | "queued" \| "running" \| "succeeded" \| "failed" \| "cancelled" | yes | Lifecycle status of the run. |
| (body).data.run.created_at | string | yes | ISO-8601 timestamp when the run was created. |
| (body).data.run.updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |
| (body).data.status_url | string | yes | Absolute URL the caller can poll for run status. |
| (body).message | string | yes | -- |

Example

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

#### 202 - Idempotent replay - the existing run matching `request_id` is returned.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | boolean | yes | `true` when the trigger was accepted. |
| (body).data | object | yes | -- |
| (body).data.run | object | yes | -- |
| (body).data.run.run_id | string | yes | MongoDB ObjectId of the run document. |
| (body).data.run.workflow_id | string | yes | ObjectId of the workflow being executed. |
| (body).data.run.status | "queued" \| "running" \| "succeeded" \| "failed" \| "cancelled" | yes | Lifecycle status of the run. |
| (body).data.run.created_at | string | yes | ISO-8601 timestamp when the run was created. |
| (body).data.run.updated_at | string | yes | ISO-8601 timestamp of the most recent state change. |
| (body).data.status_url | string | yes | Absolute URL the caller can poll for run status. |
| (body).message | string | yes | -- |

Example

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

#### 400 - Invalid workflow ID, invalid payload, or malformed request.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | false | yes | -- |
| (body).error | string | yes | Stable machine-readable error code. |
| (body).message | string | yes | Human-readable error message. |

Example

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

#### 401 - Missing or invalid bearer token.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | false | yes | -- |
| (body).error | string | yes | Stable machine-readable error code. |
| (body).message | string | yes | Human-readable error message. |

Example

```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.
Schema

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

Example

```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.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | false | yes | -- |
| (body).error | string | yes | Stable machine-readable error code. |
| (body).message | string | yes | Human-readable error message. |

Example

```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.
Schema

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

Example

```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
    }
  }
}
```

#### 400 - Invalid run ID.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | false | yes | -- |
| (body).error | string | yes | Stable machine-readable error code. |
| (body).message | string | yes | Human-readable error message. |

Example

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

#### 401 - Missing or invalid bearer token.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | false | yes | -- |
| (body).error | string | yes | Stable machine-readable error code. |
| (body).message | string | yes | Human-readable error message. |

Example

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

#### 404 - Run not found for the caller.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | false | yes | -- |
| (body).error | string | yes | Stable machine-readable error code. |
| (body).message | string | yes | Human-readable error message. |

Example

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

#### 500 - Unexpected server error.
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | object | no | -- |
| (body).success | false | yes | -- |
| (body).error | string | yes | Stable machine-readable error code. |
| (body).message | string | yes | Human-readable error message. |

Example

```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>"
```

## Public

### GET /health

API health probe

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

Responses

#### 200 - Successful Response
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | HealthResponse | no | Response shape for the API health probe. |
| (body).status | string | yes | Always `ok` when the API process is accepting requests. |

Example

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

Example

#### Request skeleton

Replace placeholder values before sending this request.

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

### GET /public/jwt-public-key

Fetch the JWT verification public key

Get the JWT public key for verifying vendor access tokens.

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

Responses

#### 200 - Successful Response
Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| (body) | JwtPublicKeyResponse | no | Response shape for the public JWT verification key endpoint. |
| (body).success | boolean | no | `true` when the key was returned. |
| (body).public_key | string | yes | PEM-encoded public key callers can use to verify access tokens issued by this API. |
| (body).algorithm | string | yes | JWT signing algorithm paired with `public_key`. |
| (body).message | string | yes | Human-readable explanation of the payload. |

Example

```json
{
  "success": true,
  "public_key": "string",
  "algorithm": "string",
  "message": "string"
}
```

Example

#### Request skeleton

Replace placeholder values before sending this request.

```bash
curl -X GET "https://api.agentpmt.com/public/jwt-public-key"
```

## 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>"
```