Programmatic Access

Programmatic API endpoints for platform integration.

Tool Calls Via REST API

GET `/credits/balance`

Get My Credit Balance

Check credit balance.

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

Parameters

Endpoint parameters
Name	Type	Required	Description
Authorization (header)	string	yes	--

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

Responses

200Current available credit balance and next expiration.

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

Field: success
Type: boolean
Required: no
Description: `true` when the balance lookup succeeded.

Field: message
Type: string
Required: no
Description: Human-readable status message.

Field: data
Type: CustomerCreditBalanceData
Required: yes
Description: --

Field: balance
Type: integer
Required: yes
Description: Current available credit balance, in whole credits (100 credits = $1).

Field: expiration
Type: string
Required: no
Description: ISO-8601 timestamp of the next credit expiration, or null when the balance is zero.anyOf variant 1 of 2

Field: expires_in_days
Type: integer
Required: no
Description: Whole days until the next expiration, or null when the balance is zero.anyOf variant 1 of 2

Example response

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

422Validation Error

Schema fields
Field	Type	Required	Description
detail	ValidationError[]	no	--
[item]	ValidationError	no	--
loc	string[]	yes	--
[item]	string	no	anyOf variant 1 of 2
msg	string	yes	--
type	string	yes	--
input	any	no	--
ctx	object	no	--

Field: detail
Type: ValidationError[]
Required: no
Description: --

Field: [item]
Type: ValidationError
Required: no
Description: --

Field: loc
Type: string[]
Required: yes
Description: --

Field: [item]
Type: string
Required: no
Description: anyOf variant 1 of 2

Field: msg
Type: string
Required: yes
Description: --

Field: type
Type: string
Required: yes
Description: --

Field: input
Type: any
Required: no
Description: --

Field: ctx
Type: object
Required: no
Description: --

Example response

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

curl -X GET "https://api.agentpmt.com/credits/balance"

GET `/credits/history`

Get My Credit History

View credit transaction history.

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

Parameters

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

Name: limit (query)
Type: integer
Required: no
Description: --

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

Responses

200Credit grants and transaction audit trail for the caller.

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

Field: success
Type: boolean
Required: no
Description: `true` when the history lookup succeeded.

Field: message
Type: string
Required: no
Description: Human-readable status message.

Field: data
Type: CustomerCreditHistoryData
Required: yes
Description: --

Field: grants
Type: CustomerCreditGrant[]
Required: yes
Description: Credit grants owned by the caller, newest first.

Field: [item]
Type: CustomerCreditGrant
Required: no
Description: --

Field: _id
Type: string
Required: yes
Description: Grant document ID (serialized as `_id` in the response).

Field: user_id
Type: string
Required: yes
Description: Owning user ID.

Field: amount_credits
Type: integer
Required: yes
Description: Credits originally granted (positive integer).

Field: amount_usd
Type: number
Required: yes
Description: USD equivalent of the grant at issuance.

Field: remaining_credits
Type: integer
Required: yes
Description: Credits still available from this grant.

Field: credit_type
Type: string
Required: yes
Description: Grant source classification (for example `admin_grant`, `referral_signup`, `x402_purchase`).

Field: source_metadata
Type: object
Required: no
Description: Free-form metadata supplied when the grant was created.

Field: date_created
Type: string
Required: yes
Description: ISO-8601 timestamp the grant was issued.

Field: pooled_at
Type: string
Required: no
Description: ISO-8601 timestamp the grant was added to the pool.anyOf variant 1 of 2

Field: expires_at
Type: string
Required: no
Description: ISO-8601 timestamp the grant expires.anyOf variant 1 of 2

Field: transactions
Type: CustomerCreditTransaction[]
Required: yes
Description: Transaction audit trail, newest first.

Field: [item]
Type: CustomerCreditTransaction
Required: no
Description: --

Field: _id
Type: string
Required: yes
Description: Transaction document ID (serialized as `_id` in the response).

Field: user_id
Type: string
Required: yes
Description: Owning user ID.

Field: transaction_type
Type: string
Required: yes
Description: One of `grant`, `expiration`, `revocation`, or `purchase` (tool deduction).

Field: amount_credits
Type: integer
Required: yes
Description: Credits applied by this transaction. Negative for debits (expiration/revocation/purchase), positive for grants.

Field: amount_usd
Type: number
Required: yes
Description: USD equivalent of the transaction.

Field: balance_after_credits
Type: integer
Required: yes
Description: Balance in credits after applying the transaction.

Field: balance_after_usd
Type: number
Required: yes
Description: Balance in USD after applying the transaction.

Field: date_created
Type: string
Required: yes
Description: ISO-8601 timestamp of the transaction.

Example response

{
  "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"
      }
    ]
  }
}

422Validation Error

Schema fields
Field	Type	Required	Description
detail	ValidationError[]	no	--
[item]	ValidationError	no	--
loc	string[]	yes	--
[item]	string	no	anyOf variant 1 of 2
msg	string	yes	--
type	string	yes	--
input	any	no	--
ctx	object	no	--

Field: detail
Type: ValidationError[]
Required: no
Description: --

Field: [item]
Type: ValidationError
Required: no
Description: --

Field: loc
Type: string[]
Required: yes
Description: --

Field: [item]
Type: string
Required: no
Description: anyOf variant 1 of 2

Field: msg
Type: string
Required: yes
Description: --

Field: type
Type: string
Required: yes
Description: --

Field: input
Type: any
Required: no
Description: --

Field: ctx
Type: object
Required: no
Description: --

Example response

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

curl -X GET "https://api.agentpmt.com/credits/history"

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: Authorization (header)
Type: string
Required: yes
Description: Bearer access token

Name: x-instance-id (header)
Type: string
Required: no
Description: Connection instance ID for persistent storage

Request Body (required)

Request model for reporting tool usage errors

Schema fields
Field	Type	Required	Description
product_id	string	yes	--
error_message	string	yes	--
recommended_improvements	string	no	--

Field: product_id
Type: string
Required: yes
Description: --

Field: error_message
Type: string
Required: yes
Description: --

Field: recommended_improvements
Type: string
Required: no
Description: --

Example request body

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

Responses

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

Schema fields
Field	Type	Required	Description
success	boolean	no	`true` when the issue report was accepted.
message	string	no	Human-readable status message.
data	IssueReportData	yes	--
issue_id	string	yes	ID of the issue document that was created.
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.
lookup_method	string	yes	How the product identifier was resolved (for example `object_id`, `slug`, `exact_name`, or `not_found`).
product_id	string	yes	Original product identifier the caller supplied.
product_name	string	no	Canonical product name, when the identifier resolved.anyOf variant 1 of 2
status	string	yes	Issue status after creation. Reports are always opened in `open`.

Field: success
Type: boolean
Required: no
Description: `true` when the issue report was accepted.

Field: message
Type: string
Required: no
Description: Human-readable status message.

Field: data
Type: IssueReportData
Required: yes
Description: --

Field: issue_id
Type: string
Required: yes
Description: ID of the issue document that was created.

Field: product_found
Type: boolean
Required: yes
Description: 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.

Field: lookup_method
Type: string
Required: yes
Description: How the product identifier was resolved (for example `object_id`, `slug`, `exact_name`, or `not_found`).

Field: product_id
Type: string
Required: yes
Description: Original product identifier the caller supplied.

Field: product_name
Type: string
Required: no
Description: Canonical product name, when the identifier resolved.anyOf variant 1 of 2

Field: status
Type: string
Required: yes
Description: Issue status after creation. Reports are always opened in `open`.

Example response

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

422Validation Error

Schema fields
Field	Type	Required	Description
detail	ValidationError[]	no	--
[item]	ValidationError	no	--
loc	string[]	yes	--
[item]	string	no	anyOf variant 1 of 2
msg	string	yes	--
type	string	yes	--
input	any	no	--
ctx	object	no	--

Field: detail
Type: ValidationError[]
Required: no
Description: --

Field: [item]
Type: ValidationError
Required: no
Description: --

Field: loc
Type: string[]
Required: yes
Description: --

Field: [item]
Type: string
Required: no
Description: anyOf variant 1 of 2

Field: msg
Type: string
Required: yes
Description: --

Field: type
Type: string
Required: yes
Description: --

Field: input
Type: any
Required: no
Description: --

Field: ctx
Type: object
Required: no
Description: --

Example response

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

curl -X POST "https://api.agentpmt.com/issues/report" \
  -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

Endpoint 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

Name: page (query)
Type: integer
Required: no
Description: Page number (1-based)

Name: page_size (query)
Type: integer
Required: no
Description: Items per page (max 100)

Name: Authorization (header)
Type: string
Required: yes
Description: Bearer access token

Name: X-Page (header)
Type: integer
Required: no
Description: Page number from header (alternative to query param)

Name: X-Page-Size (header)
Type: integer
Required: no
Description: Page size from header (alternative to query param)

Name: x-instance-id (header)
Type: string
Required: no
Description: Connection instance ID for persistent storage

Name: x-instance-metadata (header)
Type: string
Required: no
Description: Instance metadata as JSON string

Responses

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

Schema fields
Field	Type	Required	Description
success	boolean	no	`true` when the catalog was fetched successfully.
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.anyOf variant 1 of 2
details	ProductsFetchDetails	yes	--
tools_on_this_page	integer	yes	Number of tools included in this page of results.
total_qualified_tools	integer	yes	Total number of tools accessible to the caller (across all pages).
page_returned	integer	yes	Page index returned (1-based).
page_size_requested	integer	yes	Requested page size.
page_source	string	yes	`header` when the caller supplied `X-Page`; `query` otherwise.
page_size_source	string	yes	`header` when the caller supplied `X-Page-Size`; `query` otherwise.
total_pages	integer	yes	Total number of pages available.
has_next_page	boolean	yes	True when another page exists after this one.
has_previous_page	boolean	yes	True when a page exists before this one.
preprompt	string	yes	Human-readable preamble generated for downstream LLM callers. Changes based on whether any tools matched.
tools	ProductsFetchTool[]	yes	Tools available to the caller on this page.
[item]	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.
product_id	string	no	Tool ObjectId as a string.anyOf variant 1 of 2
name	string	no	Tool function name used when invoking the tool.anyOf variant 1 of 2
display_name	string	no	Human-readable product name.anyOf variant 1 of 2
description	string	no	Short description of what the tool does.anyOf variant 1 of 2
pagination	ProductsFetchPagination	yes	Canonical pagination descriptor (matches the `details` block).
page	integer	yes	Page index returned (1-based).
page_size	integer	yes	Page size used to compute this response.
total_count	integer	yes	Total number of items across all pages.
total_pages	integer	yes	Total number of pages available.
has_next	boolean	yes	True when another page exists after this one.
has_prev	boolean	yes	True when a page exists before this one.
example_tool_call	string	no	Illustrative curl command showing how to invoke one of the returned tools.anyOf variant 1 of 2

Field: success
Type: boolean
Required: no
Description: `true` when the catalog was fetched successfully.

Field: instance_id
Type: string
Required: no
Description: Connection instance ID the caller can persist and echo back via the `x-instance-id` header on subsequent calls to keep per-session context.anyOf variant 1 of 2

Field: details
Type: ProductsFetchDetails
Required: yes
Description: --

Field: tools_on_this_page
Type: integer
Required: yes
Description: Number of tools included in this page of results.

Field: total_qualified_tools
Type: integer
Required: yes
Description: Total number of tools accessible to the caller (across all pages).

Field: page_returned
Type: integer
Required: yes
Description: Page index returned (1-based).

Field: page_size_requested
Type: integer
Required: yes
Description: Requested page size.

Field: page_source
Type: string
Required: yes
Description: `header` when the caller supplied `X-Page`; `query` otherwise.

Field: page_size_source
Type: string
Required: yes
Description: `header` when the caller supplied `X-Page-Size`; `query` otherwise.

Field: total_pages
Type: integer
Required: yes
Description: Total number of pages available.

Field: has_next_page
Type: boolean
Required: yes
Description: True when another page exists after this one.

Field: has_previous_page
Type: boolean
Required: yes
Description: True when a page exists before this one.

Field: preprompt
Type: string
Required: yes
Description: Human-readable preamble generated for downstream LLM callers. Changes based on whether any tools matched.

Field: tools
Type: ProductsFetchTool[]
Required: yes
Description: Tools available to the caller on this page.

Field: [item]
Type: ProductsFetchTool
Required: no
Description: 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.

Field: product_id
Type: string
Required: no
Description: Tool ObjectId as a string.anyOf variant 1 of 2

Field: name
Type: string
Required: no
Description: Tool function name used when invoking the tool.anyOf variant 1 of 2

Field: display_name
Type: string
Required: no
Description: Human-readable product name.anyOf variant 1 of 2

Field: description
Type: string
Required: no
Description: Short description of what the tool does.anyOf variant 1 of 2

Field: pagination
Type: ProductsFetchPagination
Required: yes
Description: Canonical pagination descriptor (matches the `details` block).

Field: page
Type: integer
Required: yes
Description: Page index returned (1-based).

Field: page_size
Type: integer
Required: yes
Description: Page size used to compute this response.

Field: total_count
Type: integer
Required: yes
Description: Total number of items across all pages.

Field: total_pages
Type: integer
Required: yes
Description: Total number of pages available.

Field: has_next
Type: boolean
Required: yes
Description: True when another page exists after this one.

Field: has_prev
Type: boolean
Required: yes
Description: True when a page exists before this one.

Field: example_tool_call
Type: string
Required: no
Description: Illustrative curl command showing how to invoke one of the returned tools.anyOf variant 1 of 2

Example response

{
  "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"
}

422Validation Error

Schema fields
Field	Type	Required	Description
detail	ValidationError[]	no	--
[item]	ValidationError	no	--
loc	string[]	yes	--
[item]	string	no	anyOf variant 1 of 2
msg	string	yes	--
type	string	yes	--
input	any	no	--
ctx	object	no	--

Field: detail
Type: ValidationError[]
Required: no
Description: --

Field: [item]
Type: ValidationError
Required: no
Description: --

Field: loc
Type: string[]
Required: yes
Description: --

Field: [item]
Type: string
Required: no
Description: anyOf variant 1 of 2

Field: msg
Type: string
Required: yes
Description: --

Field: type
Type: string
Required: yes
Description: --

Field: input
Type: any
Required: no
Description: --

Field: ctx
Type: object
Required: no
Description: --

Example response

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

curl -X GET "https://api.agentpmt.com/products/fetch"

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

Endpoint 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)

Name: Authorization (header)
Type: string
Required: yes
Description: Bearer access token

Name: x-instance-id (header)
Type: string
Required: no
Description: Connection instance ID for persistent storage

Name: x-instance-metadata (header)
Type: string
Required: no
Description: Instance metadata as JSON string (AI agent info)

Request Body (required)

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.

Schema fields
Field	Type	Required	Description
product_id	string	yes	The ID of the tool (product) to purchase and invoke.
parameters	object	no	Action-specific parameters. The shape depends on the product's declared action schema.

Field: product_id
Type: string
Required: yes
Description: The ID of the tool (product) to purchase and invoke.

Field: parameters
Type: object
Required: no
Description: Action-specific parameters. The shape depends on the product's declared action schema.

Example request body

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

Responses

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

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

Field: success
Type: boolean
Required: no
Description: --

Field: data
Type: object
Required: no
Description: Tool-specific response payload returned by the product.

Field: order_id
Type: string
Required: no
Description: Identifier for the purchase/order that was created.

Field: instance_id
Type: string
Required: no
Description: Connection instance the caller can pass back via `x-instance-id` to persist state across calls.

Example response

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

422Validation Error

Schema fields
Field	Type	Required	Description
detail	ValidationError[]	no	--
[item]	ValidationError	no	--
loc	string[]	yes	--
[item]	string	no	anyOf variant 1 of 2
msg	string	yes	--
type	string	yes	--
input	any	no	--
ctx	object	no	--

Field: detail
Type: ValidationError[]
Required: no
Description: --

Field: [item]
Type: ValidationError
Required: no
Description: --

Field: loc
Type: string[]
Required: yes
Description: --

Field: [item]
Type: string
Required: no
Description: anyOf variant 1 of 2

Field: msg
Type: string
Required: yes
Description: --

Field: type
Type: string
Required: yes
Description: --

Field: input
Type: any
Required: no
Description: --

Field: ctx
Type: object
Required: no
Description: --

Example response

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

curl -X POST "https://api.agentpmt.com/products/purchase" \
  -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)

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

Field: prompt
Type: string
Required: yes
Description: Prompt forwarded to the workflow for execution.

Field: request_id
Type: string
Required: no
Description: Caller-supplied idempotency key. Retrying with the same key returns the existing run.

Field: callback_url
Type: string
Required: no
Description: HTTPS URL that will receive a POST with the final run status.

Field: request_metadata
Type: object
Required: no
Description: Free-form metadata persisted alongside the run for caller-side tracing.

Example request body

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

Responses

200Run created or existing run returned by idempotency key.

Schema fields
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" \| "succeeded" \| "failed" \| "cancelled"	yes	Lifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "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.
status_url	string	yes	Absolute URL the caller can poll for run status.
message	string	yes	--

Field: success
Type: boolean
Required: yes
Description: `true` when the trigger was accepted.

Field: data
Type: object
Required: yes
Description: --

Field: run
Type: object
Required: yes
Description: --

Field: run_id
Type: string
Required: yes
Description: MongoDB ObjectId of the run document.

Field: workflow_id
Type: string
Required: yes
Description: ObjectId of the workflow being executed.

Field: status
Type: "queued" | "running" | "succeeded" | "failed" | "cancelled"
Required: yes
Description: Lifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "cancelled"

Field: created_at
Type: string
Required: yes
Description: ISO-8601 timestamp when the run was created.

Field: updated_at
Type: string
Required: yes
Description: ISO-8601 timestamp of the most recent state change.

Field: status_url
Type: string
Required: yes
Description: Absolute URL the caller can poll for run status.

Field: message
Type: string
Required: yes
Description: --

Example response

{
  "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"
}

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

Schema fields
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" \| "succeeded" \| "failed" \| "cancelled"	yes	Lifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "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.
status_url	string	yes	Absolute URL the caller can poll for run status.
message	string	yes	--

Field: success
Type: boolean
Required: yes
Description: `true` when the trigger was accepted.

Field: data
Type: object
Required: yes
Description: --

Field: run
Type: object
Required: yes
Description: --

Field: run_id
Type: string
Required: yes
Description: MongoDB ObjectId of the run document.

Field: workflow_id
Type: string
Required: yes
Description: ObjectId of the workflow being executed.

Field: status
Type: "queued" | "running" | "succeeded" | "failed" | "cancelled"
Required: yes
Description: Lifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "cancelled"

Field: created_at
Type: string
Required: yes
Description: ISO-8601 timestamp when the run was created.

Field: updated_at
Type: string
Required: yes
Description: ISO-8601 timestamp of the most recent state change.

Field: status_url
Type: string
Required: yes
Description: Absolute URL the caller can poll for run status.

Field: message
Type: string
Required: yes
Description: --

Example response

{
  "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"
}

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

Field: success
Type: false
Required: yes
Description: enum: false

Field: error
Type: string
Required: yes
Description: Stable machine-readable error code.

Field: message
Type: string
Required: yes
Description: Human-readable error message.

Example response

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

401Missing or invalid bearer token.

Field: success
Type: false
Required: yes
Description: enum: false

Field: error
Type: string
Required: yes
Description: Stable machine-readable error code.

Field: message
Type: string
Required: yes
Description: Human-readable error message.

Example response

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

409Workflow 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 fields
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	--

Field: success
Type: false
Required: yes
Description: enum: false

Field: error
Type: "workflow_not_on_budget" | "missing_credentials" | "setup_required"
Required: yes
Description: Stable machine-readable error code.enum: "workflow_not_on_budget", "missing_credentials", "setup_required"

Field: message
Type: string
Required: yes
Description: --

Field: data
Type: object
Required: no
Description: --

Field: workflow_request_id
Type: any
Required: no
Description: Approval request ID when the workflow is not yet enabled on the budget.

Field: credential_request_ids
Type: string[]
Required: no
Description: Approval request IDs opened for the missing credentials.

Field: [item]
Type: string
Required: no
Description: --

Field: add_workflow
Type: any
Required: no
Description: Card payload describing the workflow that needs to be added.

Field: missing_credentials
Type: object[]
Required: no
Description: Requirement descriptors for credentials that still need to be configured.

Field: [item]
Type: object
Required: no
Description: --

Example response

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

500Unexpected server error.

Field: success
Type: false
Required: yes
Description: enum: false

Field: error
Type: string
Required: yes
Description: Stable machine-readable error code.

Field: message
Type: string
Required: yes
Description: Human-readable error message.

Example response

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

curl -X POST "https://www.agentpmt.com/api/agent-webhooks/example-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

200Current status and payload of the workflow run.

Schema fields
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" \| "succeeded" \| "failed" \| "cancelled"	yes	Lifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "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.

Field: success
Type: boolean
Required: yes
Description: `true` when the run was located.

Field: data
Type: object
Required: yes
Description: --

Field: run
Type: object
Required: yes
Description: --

Field: run_id
Type: string
Required: yes
Description: MongoDB ObjectId of the run document.

Field: workflow_id
Type: string
Required: yes
Description: ObjectId of the workflow being executed.

Field: status
Type: "queued" | "running" | "succeeded" | "failed" | "cancelled"
Required: yes
Description: Lifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "cancelled"

Field: prompt
Type: string
Required: yes
Description: Original prompt supplied when the run was triggered.

Field: response_text
Type: any
Required: no
Description: Final model response text once the run completes.

Field: session_id
Type: any
Required: no
Description: Chat session ID bound to this run, when available.

Field: model
Type: any
Required: no
Description: Model used to execute the run, when known.

Field: error_code
Type: any
Required: no
Description: Stable error code when the run failed.

Field: error_message
Type: any
Required: no
Description: Human-readable error message when the run failed.

Field: callback_url
Type: any
Required: no
Description: Registered callback URL, if the caller supplied one.

Field: callback_status
Type: "pending" | "delivered" | "failed" | "skipped"
Required: yes
Description: Delivery status of the callback.enum: "pending", "delivered", "failed", "skipped"

Field: callback_last_status
Type: any
Required: no
Description: HTTP status code from the most recent callback attempt.

Field: callback_last_error
Type: any
Required: no
Description: Error message from the most recent failed callback attempt.

Field: callback_attempted_at
Type: any
Required: no
Description: ISO-8601 timestamp of the most recent callback attempt.

Field: callback_delivered_at
Type: any
Required: no
Description: ISO-8601 timestamp when the callback was delivered successfully.

Field: request_metadata
Type: object
Required: no
Description: Metadata supplied with the original trigger request.

Field: run_metadata
Type: object
Required: no
Description: Internal per-run metadata captured during execution.

Field: created_at
Type: string
Required: yes
Description: ISO-8601 timestamp when the run was created.

Field: updated_at
Type: string
Required: yes
Description: ISO-8601 timestamp of the most recent state change.

Field: started_at
Type: any
Required: no
Description: ISO-8601 timestamp when execution began.

Field: completed_at
Type: any
Required: no
Description: ISO-8601 timestamp when execution finished, if completed.

Example response

{
  "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
    }
  }
}

400Invalid run ID.

Field: success
Type: false
Required: yes
Description: enum: false

Field: error
Type: string
Required: yes
Description: Stable machine-readable error code.

Field: message
Type: string
Required: yes
Description: Human-readable error message.

Example response

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

401Missing or invalid bearer token.

Field: success
Type: false
Required: yes
Description: enum: false

Field: error
Type: string
Required: yes
Description: Stable machine-readable error code.

Field: message
Type: string
Required: yes
Description: Human-readable error message.

Example response

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

404Run not found for the caller.

Field: success
Type: false
Required: yes
Description: enum: false

Field: error
Type: string
Required: yes
Description: Stable machine-readable error code.

Field: message
Type: string
Required: yes
Description: Human-readable error message.

Example response

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

500Unexpected server error.

Field: success
Type: false
Required: yes
Description: enum: false

Field: error
Type: string
Required: yes
Description: Stable machine-readable error code.

Field: message
Type: string
Required: yes
Description: Human-readable error message.

Example response

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

curl -X GET "https://www.agentpmt.com/api/agent-webhooks/runs/example-runId"

Public

GET `/health`

API health probe

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

Responses

200Successful Response

Response shape for the API health probe.

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

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

Example response

{
  "status": "string"
}

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

200Successful Response

Response shape for the public JWT verification key endpoint.

Schema fields
Field	Type	Required	Description
success	boolean	no	`true` when the key was returned.
public_key	string	yes	PEM-encoded public key callers can use to verify access tokens issued by this API.
algorithm	string	yes	JWT signing algorithm paired with `public_key`.
message	string	yes	Human-readable explanation of the payload.

Field: success
Type: boolean
Required: no
Description: `true` when the key was returned.

Field: public_key
Type: string
Required: yes
Description: PEM-encoded public key callers can use to verify access tokens issued by this API.

Field: algorithm
Type: string
Required: yes
Description: JWT signing algorithm paired with `public_key`.

Field: message
Type: string
Required: yes
Description: Human-readable explanation of the payload.

Example response

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

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

200Loader 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.

400Bad request

No response body schema published.

401Unauthorized

No response body schema published.

500Internal server error

No response body schema published.

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

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

Returns HTML document.

400Bad request

No response body schema published.

401Unauthorized

No response body schema published.

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

Returns HTML document.

500Internal server error

No response body schema published.

curl -X GET "https://www.agentpmt.com/embed/example-workflowId"

GET `/embed/bundle/{bundleId}`

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

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

Responses

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

Returns HTML document.

400Bad request

No response body schema published.

401Unauthorized

No response body schema published.

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

Returns HTML document.

500Internal server error

No response body schema published.

curl -X GET "https://www.agentpmt.com/embed/bundle/example-bundleId"

GET `/embed/product/{productId}`

Embed the chat widget scoped to a single product tool

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

Responses

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

Returns HTML document.

400Bad request

No response body schema published.

401Unauthorized

No response body schema published.

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

Returns HTML document.

500Internal server error

No response body schema published.

curl -X GET "https://www.agentpmt.com/embed/product/example-productId"

Start building with what you just read.

Create a free account to try these workflows, or browse the marketplace.

Browse agents

Free to start. No card required.

Tool Calls Via REST API

GET /credits/balance

Parameters

Responses

Example response

Example response

GET /credits/history

Parameters

Responses

Example response

Example response

POST /issues/report

Parameters

Request Body (required)

Example request body

Responses

Example response

Example response

GET /products/fetch

Parameters

Responses

Example response

Example response

POST /products/purchase

Parameters

Request Body (required)

Example request body

Responses

Example response

Example response

Trigger Autonomous Workflows Via Webhooks

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

Request Body (required)

Example request body

Responses

Example response

Example response

Example response

Example response

Example response

Example response

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

Responses

Example response

Example response

Example response

Example response

Example response

Public

GET /health

Responses

Example response

GET /public/jwt-public-key

Responses

Example response

Embedding

GET /embed.js

Responses

GET /embed/{workflowId}

Responses

GET /embed/bundle/{bundleId}

Responses

GET /embed/product/{productId}

Responses

Start building with what you just read.

GET `/credits/balance`

GET `/credits/history`

POST `/issues/report`

GET `/products/fetch`

POST `/products/purchase`

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

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

GET `/health`

GET `/public/jwt-public-key`

GET `/embed.js`

GET `/embed/{workflowId}`

GET `/embed/bundle/{bundleId}`

GET `/embed/product/{productId}`