Configure an API connector

An API connector lets an agent call an external HTTP endpoint. Configure the endpoint once, then use request templates to map values supplied at run time into headers, query parameters, and request bodies.

Before you begin

You need:

The external API URL and HTTP method.
The required headers, query parameters, and body shape.
Authentication credentials if the API is protected.
Permission to add tools and assign them to an agent.

Store secrets in the connector authentication configuration. Do not include credentials in prompts or other user-controlled runtime values.

Configure the request

Create an api_connector tool and configure these fields:

Field	Purpose
`url`	External API endpoint.
`method`	HTTP method. Defaults to `GET`.
`headers_template`	Headers added to each request. The legacy `headers` field is also accepted.
`params_template`	Query parameters added to each request. The legacy `params` field is also accepted.
`body_template`	Request body added to each request. The legacy `body` field is also accepted.
`timeout`	Request timeout in seconds. Defaults to `10`.

Templates can be JSON objects or JSON-encoded strings. Objects and arrays are resolved recursively.

Use runtime placeholders

Insert a runtime value with {{variable_name}}. Placeholder names can contain letters, numbers, and underscores. At run time, Pinter builds the placeholder context from the JSON objects passed as params, headers, and body. If the body is plain text instead of JSON, the same value is exposed as prompt, message, body, and text. For example, this body template maps agent input into an external ticket API:

{
  "title": "Agent request for {{customer_id}}",
  "description": "{{message}}",
  "priority": "{{priority}}"
}

A placeholder that occupies the complete JSON value preserves the runtime value type. For example, "active": "{{is_active}}" can resolve to a Boolean. A placeholder embedded inside a longer string resolves to text.

An unresolved placeholder remains in {{variable_name}} form. Test the tool with representative inputs before assigning it to an agent.

Configure token authentication

Use the authentication fields when the connector must obtain a bearer token before calling the target API:

Field	Purpose
`authentication_url`	Endpoint used to obtain the token.
`authentication_method`	Authentication HTTP method. Defaults to `POST`.
`authentication_header`	Headers sent to the authentication endpoint. The legacy `authentication_headers` field is also accepted.
`authentication_body`	Body sent to the authentication endpoint.
`authentication_token_key`	Response field containing the token. Defaults to `access_token`.

Pinter caches the token for the configured lifetime and sends it to the target API as Authorization: Bearer <token>.

Test and assign the connector

Test the request

Run the connector with JSON values that cover every required template field. Check the returned status and response body.

Check unresolved values

Confirm that the outgoing request does not contain any remaining {{variable_name}} placeholders.

Assign the tool

Open the agent builder and add the API connector tool to the agent.

Run an agent evaluation

Verify that the agent supplies the expected headers, parameters, and body values for representative prompts.

Troubleshooting

Symptom	Check
A required field is missing	Pass all keys represented by the configured template.
A placeholder is not replaced	Confirm the runtime JSON contains the same variable name.
Authentication fails	Check the authentication URL, credentials, and token response field.
The request times out	Verify network access and increase `timeout` only when the API requires it.

Get started

Architecture

Core workflows

Administration

Reference

Configure an API connector

Before you begin

Configure the request

Use runtime placeholders

Configure token authentication

Test and assign the connector

Troubleshooting

​Before you begin

​Configure the request

​Use runtime placeholders

​Configure token authentication

​Test and assign the connector

​Troubleshooting

Before you begin

Configure the request

Use runtime placeholders

Configure token authentication

Test and assign the connector

Troubleshooting