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

NameTypeRequiredDescription
Authorization (header)stringyes--

Responses

200Current available credit balance and next expiration.
FieldTypeRequiredDescription
successbooleanno`true` when the balance lookup succeeded.
messagestringnoHuman-readable status message.
dataCustomerCreditBalanceDatayes--
balanceintegeryesCurrent available credit balance, in whole credits (100 credits = $1).
expirationstringnoISO-8601 timestamp of the next credit expiration, or null when the balance is zero.anyOf variant 1 of 2
expires_in_daysintegernoWhole 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
FieldTypeRequiredDescription
detailValidationError[]no--
[item]ValidationErrorno--
locstring[]yes--
[item]stringnoanyOf variant 1 of 2
msgstringyes--
typestringyes--
inputanyno--
ctxobjectno--

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

NameTypeRequiredDescription
limit (query)integerno--
Authorization (header)stringyes--

Responses

200Credit grants and transaction audit trail for the caller.
FieldTypeRequiredDescription
successbooleanno`true` when the history lookup succeeded.
messagestringnoHuman-readable status message.
dataCustomerCreditHistoryDatayes--
grantsCustomerCreditGrant[]yesCredit grants owned by the caller, newest first.
[item]CustomerCreditGrantno--
_idstringyesGrant document ID (serialized as `_id` in the response).
user_idstringyesOwning user ID.
amount_creditsintegeryesCredits originally granted (positive integer).
amount_usdnumberyesUSD equivalent of the grant at issuance.
remaining_creditsintegeryesCredits still available from this grant.
credit_typestringyesGrant source classification (for example `admin_grant`, `referral_signup`, `x402_purchase`).
source_metadataobjectnoFree-form metadata supplied when the grant was created.
date_createdstringyesISO-8601 timestamp the grant was issued.
pooled_atstringnoISO-8601 timestamp the grant was added to the pool.anyOf variant 1 of 2
expires_atstringnoISO-8601 timestamp the grant expires.anyOf variant 1 of 2
transactionsCustomerCreditTransaction[]yesTransaction audit trail, newest first.
[item]CustomerCreditTransactionno--
_idstringyesTransaction document ID (serialized as `_id` in the response).
user_idstringyesOwning user ID.
transaction_typestringyesOne of `grant`, `expiration`, `revocation`, or `purchase` (tool deduction).
amount_creditsintegeryesCredits applied by this transaction. Negative for debits (expiration/revocation/purchase), positive for grants.
amount_usdnumberyesUSD equivalent of the transaction.
balance_after_creditsintegeryesBalance in credits after applying the transaction.
balance_after_usdnumberyesBalance in USD after applying the transaction.
date_createdstringyesISO-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
FieldTypeRequiredDescription
detailValidationError[]no--
[item]ValidationErrorno--
locstring[]yes--
[item]stringnoanyOf variant 1 of 2
msgstringyes--
typestringyes--
inputanyno--
ctxobjectno--

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

NameTypeRequiredDescription
Authorization (header)stringyesBearer access token
x-instance-id (header)stringnoConnection instance ID for persistent storage

Request Body (required)

Request model for reporting tool usage errors

FieldTypeRequiredDescription
product_idstringyes--
error_messagestringyes--
recommended_improvementsstringno--

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.
FieldTypeRequiredDescription
successbooleanno`true` when the issue report was accepted.
messagestringnoHuman-readable status message.
dataIssueReportDatayes--
issue_idstringyesID of the issue document that was created.
product_foundbooleanyesTrue 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_methodstringyesHow the product identifier was resolved (for example `object_id`, `slug`, `exact_name`, or `not_found`).
product_idstringyesOriginal product identifier the caller supplied.
product_namestringnoCanonical product name, when the identifier resolved.anyOf variant 1 of 2
statusstringyesIssue 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
FieldTypeRequiredDescription
detailValidationError[]no--
[item]ValidationErrorno--
locstring[]yes--
[item]stringnoanyOf variant 1 of 2
msgstringyes--
typestringyes--
inputanyno--
ctxobjectno--

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

NameTypeRequiredDescription
page (query)integernoPage number (1-based)
page_size (query)integernoItems per page (max 100)
Authorization (header)stringyesBearer access token
X-Page (header)integernoPage number from header (alternative to query param)
X-Page-Size (header)integernoPage size from header (alternative to query param)
x-instance-id (header)stringnoConnection instance ID for persistent storage
x-instance-metadata (header)stringnoInstance metadata as JSON string

Responses

200Paginated list of tools available to the caller, plus a pre-prompt and a sample tool-call curl.
FieldTypeRequiredDescription
successbooleanno`true` when the catalog was fetched successfully.
instance_idstringnoConnection 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
detailsProductsFetchDetailsyes--
tools_on_this_pageintegeryesNumber of tools included in this page of results.
total_qualified_toolsintegeryesTotal number of tools accessible to the caller (across all pages).
page_returnedintegeryesPage index returned (1-based).
page_size_requestedintegeryesRequested page size.
page_sourcestringyes`header` when the caller supplied `X-Page`; `query` otherwise.
page_size_sourcestringyes`header` when the caller supplied `X-Page-Size`; `query` otherwise.
total_pagesintegeryesTotal number of pages available.
has_next_pagebooleanyesTrue when another page exists after this one.
has_previous_pagebooleanyesTrue when a page exists before this one.
prepromptstringyesHuman-readable preamble generated for downstream LLM callers. Changes based on whether any tools matched.
toolsProductsFetchTool[]yesTools available to the caller on this page.
[item]ProductsFetchToolnoLoose 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_idstringnoTool ObjectId as a string.anyOf variant 1 of 2
namestringnoTool function name used when invoking the tool.anyOf variant 1 of 2
display_namestringnoHuman-readable product name.anyOf variant 1 of 2
descriptionstringnoShort description of what the tool does.anyOf variant 1 of 2
paginationProductsFetchPaginationyesCanonical pagination descriptor (matches the `details` block).
pageintegeryesPage index returned (1-based).
page_sizeintegeryesPage size used to compute this response.
total_countintegeryesTotal number of items across all pages.
total_pagesintegeryesTotal number of pages available.
has_nextbooleanyesTrue when another page exists after this one.
has_prevbooleanyesTrue when a page exists before this one.
example_tool_callstringnoIllustrative 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
FieldTypeRequiredDescription
detailValidationError[]no--
[item]ValidationErrorno--
locstring[]yes--
[item]stringnoanyOf variant 1 of 2
msgstringyes--
typestringyes--
inputanyno--
ctxobjectno--

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

NameTypeRequiredDescription
Authorization (header)stringyesBearer access token
x-instance-id (header)stringnoConnection instance ID for persistent storage
x-instance-metadata (header)stringnoInstance 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.

FieldTypeRequiredDescription
product_idstringyesThe ID of the tool (product) to purchase and invoke.
parametersobjectnoAction-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.
FieldTypeRequiredDescription
successbooleanno--
dataobjectnoTool-specific response payload returned by the product.
order_idstringnoIdentifier for the purchase/order that was created.
instance_idstringnoConnection 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
FieldTypeRequiredDescription
detailValidationError[]no--
[item]ValidationErrorno--
locstring[]yes--
[item]stringnoanyOf variant 1 of 2
msgstringyes--
typestringyes--
inputanyno--
ctxobjectno--

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/external/agent-webhooks/{workflowId}/trigger

Trigger a workflow run

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

Request Body (required)

FieldTypeRequiredDescription
promptstringyesPrompt forwarded to the workflow for execution.
request_idstringnoCaller-supplied idempotency key. Retrying with the same key returns the existing run.
callback_urlstringnoHTTPS URL that will receive a POST with the final run status.
request_metadataobjectnoFree-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.
FieldTypeRequiredDescription
successbooleanyes`true` when the trigger was accepted.
dataobjectyes--
runobjectyes--
run_idstringyesMongoDB ObjectId of the run document.
workflow_idstringyesObjectId of the workflow being executed.
status"queued" | "running" | "succeeded" | "failed" | "cancelled"yesLifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "cancelled"
created_atstringyesISO-8601 timestamp when the run was created.
updated_atstringyesISO-8601 timestamp of the most recent state change.
status_urlstringyesAbsolute URL the caller can poll for run status.
messagestringyes--

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.
FieldTypeRequiredDescription
successbooleanyes`true` when the trigger was accepted.
dataobjectyes--
runobjectyes--
run_idstringyesMongoDB ObjectId of the run document.
workflow_idstringyesObjectId of the workflow being executed.
status"queued" | "running" | "succeeded" | "failed" | "cancelled"yesLifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "cancelled"
created_atstringyesISO-8601 timestamp when the run was created.
updated_atstringyesISO-8601 timestamp of the most recent state change.
status_urlstringyesAbsolute URL the caller can poll for run status.
messagestringyes--

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.
FieldTypeRequiredDescription
successfalseyesenum: false
errorstringyesStable machine-readable error code.
messagestringyesHuman-readable error message.

Example response

{
  "success": false,
  "error": "string",
  "message": "string"
}
401Missing or invalid bearer token.
FieldTypeRequiredDescription
successfalseyesenum: false
errorstringyesStable machine-readable error code.
messagestringyesHuman-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.
FieldTypeRequiredDescription
successfalseyesenum: false
error"workflow_not_on_budget" | "missing_credentials" | "setup_required"yesStable machine-readable error code.enum: "workflow_not_on_budget", "missing_credentials", "setup_required"
messagestringyes--
dataobjectno--
workflow_request_idanynoApproval request ID when the workflow is not yet enabled on the budget.
credential_request_idsstring[]noApproval request IDs opened for the missing credentials.
[item]stringno--
add_workflowanynoCard payload describing the workflow that needs to be added.
missing_credentialsobject[]noRequirement descriptors for credentials that still need to be configured.
[item]objectno--

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.
FieldTypeRequiredDescription
successfalseyesenum: false
errorstringyesStable machine-readable error code.
messagestringyesHuman-readable error message.

Example response

{
  "success": false,
  "error": "string",
  "message": "string"
}
curl -X POST "https://www.agentpmt.com/api/external/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/external/agent-webhooks/runs/{runId}

Get workflow run status

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

Responses

200Current status and payload of the workflow run.
FieldTypeRequiredDescription
successbooleanyes`true` when the run was located.
dataobjectyes--
runobjectyes--
run_idstringyesMongoDB ObjectId of the run document.
workflow_idstringyesObjectId of the workflow being executed.
status"queued" | "running" | "succeeded" | "failed" | "cancelled"yesLifecycle status of the run.enum: "queued", "running", "succeeded", "failed", "cancelled"
promptstringyesOriginal prompt supplied when the run was triggered.
response_textanynoFinal model response text once the run completes.
session_idanynoChat session ID bound to this run, when available.
modelanynoModel used to execute the run, when known.
error_codeanynoStable error code when the run failed.
error_messageanynoHuman-readable error message when the run failed.
callback_urlanynoRegistered callback URL, if the caller supplied one.
callback_status"pending" | "delivered" | "failed" | "skipped"yesDelivery status of the callback.enum: "pending", "delivered", "failed", "skipped"
callback_last_statusanynoHTTP status code from the most recent callback attempt.
callback_last_erroranynoError message from the most recent failed callback attempt.
callback_attempted_atanynoISO-8601 timestamp of the most recent callback attempt.
callback_delivered_atanynoISO-8601 timestamp when the callback was delivered successfully.
request_metadataobjectnoMetadata supplied with the original trigger request.
run_metadataobjectnoInternal per-run metadata captured during execution.
created_atstringyesISO-8601 timestamp when the run was created.
updated_atstringyesISO-8601 timestamp of the most recent state change.
started_atanynoISO-8601 timestamp when execution began.
completed_atanynoISO-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.
FieldTypeRequiredDescription
successfalseyesenum: false
errorstringyesStable machine-readable error code.
messagestringyesHuman-readable error message.

Example response

{
  "success": false,
  "error": "string",
  "message": "string"
}
401Missing or invalid bearer token.
FieldTypeRequiredDescription
successfalseyesenum: false
errorstringyesStable machine-readable error code.
messagestringyesHuman-readable error message.

Example response

{
  "success": false,
  "error": "string",
  "message": "string"
}
404Run not found for the caller.
FieldTypeRequiredDescription
successfalseyesenum: false
errorstringyesStable machine-readable error code.
messagestringyesHuman-readable error message.

Example response

{
  "success": false,
  "error": "string",
  "message": "string"
}
500Unexpected server error.
FieldTypeRequiredDescription
successfalseyesenum: false
errorstringyesStable machine-readable error code.
messagestringyesHuman-readable error message.

Example response

{
  "success": false,
  "error": "string",
  "message": "string"
}
curl -X GET "https://www.agentpmt.com/api/external/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.

FieldTypeRequiredDescription
statusstringyesAlways `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.

FieldTypeRequiredDescription
successbooleanno`true` when the key was returned.
public_keystringyesPEM-encoded public key callers can use to verify access tokens issued by this API.
algorithmstringyesJWT signing algorithm paired with `public_key`.
messagestringyesHuman-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"