Skip to main content

API Tools

This guide walks you through creating an API tool that your AI agents can use to interact with external systems.

What are API Tools?​

API Tools allow your AI agent to connect to external systems and perform actions on behalf of customers:

  • Lookups: Check order status, view account balance, find product availability
  • Actions: Create orders, update customer info, trigger workflows
  • Integrations: Connect to CRMs, ERPs, payment systems, shipping APIs

When a customer asks something that requires external data, the AI agent automatically calls the configured API tool, gets the response, and uses that information to reply.

Accessing API Tools​

  1. Go to Integrations in the sidebar
  2. Click Tools
  3. Click Add Tool to create a new tool

Form Sections​

Basic Information​

FieldDescriptionRequirements
Tool TitleInternal name for the tool (shown to AI)3-55 characters, starts with letter, alphanumeric + underscores only
DescriptionExplains what this tool does — the AI uses this to decide when to call it10-5000 characters

Examples of good tool titles:

  • get_order_status
  • create_support_ticket
  • check_inventory

Tip: Write the description as if explaining to a human assistant when they should use this tool.

Good description:

"Retrieves order details including status, items, and shipping info by order ID. Use when customer asks about their order status, tracking, or delivery."

Too vague:

"Get order info"

API Configuration​

FieldDescriptionExample
Base URLThe root URL of the API (must be public HTTPS/HTTP)https://api.yourcrm.com
MethodHTTP method: GET, POST, PUT, DELETEGET for fetching, POST for creating
Endpoint TemplateThe API path (can include variables)/orders/{{order_id}}

Important: Base URL must be publicly accessible. Private IPs (192.168.x.x, 10.x.x.x), localhost, and 127.0.0.1 are not allowed.

Variables — Just Like Postman!​

Variables work exactly like Postman environment variables. Use double curly braces {{variable_name}} to insert dynamic values.

Two Types of Variables​

1. Components — Custom variables extracted from conversation​

Syntax: {{component_name}}
Examples: {{order_id}}, {{product_sku}}, {{search_query}}

The AI agent extracts these values from customer messages. For example, when a customer says "What's the status of order #12345?", the AI extracts 12345 as the order_id component.

2. User Attributes — Pre-filled from customer profile​

Syntax: {{$attribute_name}}
Available: {{$name}}, {{$email}}, {{$phone}}, {{$location}}, {{$language}}, {{$instagram_username}}

These are automatically filled from the customer's profile data.

Where Can You Use Variables?​

LocationExample
Endpoint/users/{{user_id}}/orders
Query Parametersemail={{$email}}&status={{order_status}}
HeadersAuthorization: Bearer {{api_token}}
Request Body (JSON){"customer_id": "{{customer_id}}", "email": "{{$email}}"}
Request Body (Form)name={{$name}}&order={{order_id}}

Query Parameters​

Add URL query parameters as key-value pairs. These are appended to the URL as ?key=value&key2=value2.

KeyValueResult
order_id{{order_id}}?order_id=12345
email{{$email}}?email=customer@example.com
limit10?limit=10 (static value)

Headers​

Add custom HTTP headers. Common uses:

HeaderValuePurpose
AuthorizationBearer {{api_token}}API authentication
X-API-Key{{api_key}}Alternative auth method
X-Customer-ID{{$email}}Pass customer context
note

Content-Type is automatically set based on your body type selection — you cannot manually set it.

Request Body​

For POST/PUT methods, you can send data in the request body.

Body Types:

  • JSON (application/json) — Most common for modern APIs
  • Form URL Encoded (application/x-www-form-urlencoded) — Traditional form submission
  • Multipart Form (multipart/form-data) — For file uploads

JSON Body Example:

{
  "customer_email": "{{$email}}",
  "customer_name": "{{$name}}",
  "order_id": "{{order_id}}",
  "quantity": {{quantity}},
  "notes": "{{special_instructions}}"
}
Important for JSON

For numeric and boolean values, do NOT use quotes around the variable:

  • String: "name": "{{$name}}" (with quotes)
  • Number: "quantity": {{quantity}} (no quotes)
  • Boolean: "active": {{is_active}} (no quotes)

JOLT Specification (Optional but Powerful)​

What is JOLT?

JOLT (JSON to JSON Transformation Language) transforms the API response into a simpler format before the AI agent receives it.

When to use JOLT:

  • The API returns complex nested data that confuses the AI
  • You want to extract only specific fields
  • You need to rename fields to be more descriptive
  • The response is too large and you want to trim it down

Why Use JOLT?

  1. Cleaner AI responses — The AI works better with simple, flat data
  2. Reduce token usage — Smaller responses = faster, cheaper AI processing
  3. Hide sensitive data — Only pass relevant fields to the AI
  4. Standardize formats — Make different APIs return consistent structures

JOLT Example​

API returns:

{
  "data": {
    "order": {
      "id": "ORD-123",
      "customer": {
        "name": "John",
        "contact": { "email": "john@example.com" }
      },
      "status": "shipped",
      "items": [...]
    }
  }
}

JOLT Spec to flatten:

[
  {
    "operation": "shift",
    "spec": {
      "data": {
        "order": {
          "id": "order_id",
          "status": "order_status",
          "customer": {
            "name": "customer_name"
          }
        }
      }
    }
  }
]

Transformed result:

{
  "order_id": "ORD-123",
  "order_status": "shipped",
  "customer_name": "John"
}

Common JOLT Operations:

  • shift — Move/rename fields (most common)
  • default — Add default values for missing fields
  • remove — Delete unwanted fields

Generating JOLT with AI​

Don't want to write JOLT manually? Use any LLM (like ChatGPT or Claude) to generate it for you:

  1. Copy your API response
  2. Tell the LLM: "Generate a JOLT spec that extracts X, Y, Z from this response and renames them to be clearer"
  3. Paste the generated spec into Orki

Example prompt:

"Here's my API response: [paste JSON]. Generate a JOLT spec that extracts the order ID, status, and customer name, and renames them to order_id, order_status, and customer_name."

Renaming for Clarity​

JOLT is especially useful for renaming cryptic field names to something the AI understands better:

Original FieldRenamed ToWhy
ord_stsorder_statusClearer meaning
cust_nmcustomer_nameAI understands "name"
dlvry_dtdelivery_dateRemoves abbreviations

Referenced Variables Section​

This section auto-populates based on variables used in your configuration.

Required Checkbox:

  • Checked — If this value is missing, the AI will ask the customer to provide it before calling the API
  • Unchecked — The variable is optional; the API will be called even if the value is missing

Color Coding:

  • Blue chip — Valid component (exists in your components list)
  • Purple chip — Valid user attribute
  • Red chip — Invalid reference (component doesn't exist or typo in attribute name)

Creating Components​

Before using {{component_name}} variables, you need to create the component. Components define what type of data the AI should extract from conversations.

Component Types​

TypeDescriptionExample Use
StringText valuesorder_id, product_name, search_query
NumberNumeric valuesquantity, price, age
BooleanTrue/falseis_urgent, wants_notification
EnumPredefined optionsorder_status (pending/shipped/delivered)
ObjectComplex nested datashipping_address with street, city, zip
ArrayList of valuesproduct_ids, selected_options

Creating a Component​

  1. Click on a component chip in the Referenced Variables section
  2. Or navigate to Components section and click "Add Component"
  3. Fill in:
    • Name — snake_case identifier (e.g., order_id)
    • Description — Explain what this data represents (helps AI extract correctly)
    • Type — Select appropriate type
    • Example Value — Sample data for documentation

Complete Example: Order Lookup Tool​

Scenario: Create a tool that looks up order status from your e-commerce API.

Basic Information​

  • Title: get_order_status
  • Description: Retrieves order details including current status, shipping information, and estimated delivery date. Use when customer asks about their order status, tracking, or delivery.

API Configuration​

  • Base URL: https://api.mystore.com
  • Method: GET
  • Endpoint: /v1/orders/{{order_id}}

Headers​

HeaderValue
AuthorizationBearer sk_live_xxxxxxxxxxxxx
X-Customer-Email{{$email}}

Query Parameters​

KeyValue
includeshipping,items

JOLT Specification​

[
  {
    "operation": "shift",
    "spec": {
      "order_number": "order_number",
      "status": "status",
      "created_at": "order_date",
      "shipping": {
        "carrier": "shipping_carrier",
        "tracking_number": "tracking_number",
        "estimated_delivery": "delivery_date"
      },
      "total": "total_amount"
    }
  }
]

Referenced Variables​

  • order_id — Required (checked) — AI will ask customer for order number if not provided
  • $email — Optional — used for verification

Assigning Tools to Agents​

After creating a tool, you need to assign it to an agent:

  1. Go to Agents
  2. Click on the agent
  3. Go to the Tools tab
  4. Click Available Tools
  5. Click Assign to Agent on your new tool

See Agent Tools for more details.

Tips for Better Tool Usage​

Write Descriptions with Expected Outcomes​

Include what the tool returns in your description. This helps the AI understand when to use it:

Good description:

"Retrieves order details including order status, tracking number, shipping carrier, and estimated delivery date. Use when customer asks about their order status, tracking, or delivery."

Less helpful:

"Gets order information."

The AI now knows this tool returns tracking numbers, so it will use it when customers ask "Where's my tracking number?"

Managing Many Tools​

If you have many tools, the AI might get confused about which one to use. Help it by updating your Agent Personality with Custom Instructions that explain when to use each tool:

Example Custom Instructions:

TOOL USAGE GUIDELINES:
- Use `get_order_status` when customer asks about order status, tracking, or delivery
- Use `check_inventory` when customer asks if a product is in stock
- Use `create_support_ticket` only when the issue cannot be resolved and needs human follow-up
- Always try `get_order_status` before `create_support_ticket` for order-related issues

This guidance in Custom Instructions helps the AI make better decisions about which tool to call.

IssueSolution
"Invalid component" error (red chip)Create the component first, or check for typos in the name
"Base URL must be public domain"Use your production API URL, not localhost or internal IPs
"Invalid JSON" in request bodyCheck for missing commas, unquoted keys, or trailing commas
API returns but AI gives wrong answerAdd JOLT spec to simplify/flatten the response
"Content-Type cannot be set"Remove Content-Type from headers; it's auto-set based on body type

Tool Limits​

The number of tools you can create depends on your plan. Check your limits in Settings > Billing.

Next Steps​