API Documentation

The BoundaryAI API allows you to programmatically push feedback data, create data sources, and manage your organization's feedback collection workflow.

Overview

The BoundaryAI API enables you to programmatically import feedback data from any source- support tickets, CRM exports, surveys, chat logs - and leverage AI-powered analysis to extract insights.

Core Concepts

Before diving in, understand these key concepts:

Concept

Description

Feedback Group

A container that organizes related data sources (e.g., "Q1 2024 Customer Feedback")

Data Source

A collection of feedback within a group (e.g., "Zendesk Tickets", "NPS Survey")

Question

A field within a data source that holds feedback text

APS

Analysis Points - credits consumed when pushing content for AI analysis

How It Works

1. Create a Feedback Group (or use existing)
         ↓
2. Create a Data Source with Questions
         ↓
3. Publish the Data Source
         ↓
4. Push your feedback content
         ↓
5. BoundaryAI analyzes and extracts insights

Authentication

API Keys

All API requests require an API key passed in the Authorization header:

Authorization: Bearer inpk_live_abc123xyz_SbcEpUl9DWuI8IOI-YImkxPNSisaAab7t0goFuliM-4

Key Format

inpk_{environment}_{key_id}_{secret}

Part

Description

inpk

Fixed prefix (Input API Key)

environment

live (production) or test (no APS deduction)

key_id

10-character unique identifier

secret

Base64-encoded secret (44 characters)

Key Permissions

When creating an API key, you choose its permission level:

Permission

Can Do

Use Case

push

Push content to existing data sources

Automated import scripts

create

Create feedback groups and data sources

Setup automation

all

Everything

Full programmatic control

Getting Your API Key

Go to Integrations → API in your BoundaryAI dashboard
Click Create API Key
Choose a name, environment, and permission level
Save the key immediately — it's only shown once!

Security Notes

Keys are hashed server-side; we never store the plaintext
Use test environment keys during development (no APS charges)
Rotate keys regularly via the dashboard
Never commit keys to version control

Making Requests

Base URLs

Environment

Base URL

Europe

https://app.boundary-ai.com/

North America

https://app.boundary-ai.com/

APAC

Coming soon

Request Format

All requests must include:

Authorization: Bearer {your_api_key}
Content-Type: application/json

Response Format

Success Response

{
  "status": "success",
  "inserted": 3,
  "aps_deducted": 3
}

Error Response

{
  "error": {
    "code": "SURVEY_NOT_FOUND",
    "message": "Data source with ID 999 does not exist",
    "details": {}
  }
}

Rate Limiting

Three layers protect the API:

Layer

Limit

Scope

Per-Key

60/min (configurable)

Individual API key

Per-Org

300/min

All keys in organization

Per-IP

600/min

Fallback protection

Response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1704067200

When rate limited, you'll receive HTTP 429 with a Retry-After header.

Idempotency

Prevent duplicate data by including an idempotency key:

Idempotency-Key: import-batch-2024-01-15-001

Scenario

Result

First request

Executes normally, caches response for 24h

Same key + same payload

Returns cached response (no duplicate insert)

Same key + different payload

Returns HTTP 409 conflict error

Best practice: Use a unique identifier like {source}-{date}-{batch} for each import batch.

Endpoints Reference

Quick Reference

Method

Endpoint

Description

Permission

GET

/api/input/surveys/list

List all feedback groups & data sources

any

POST

/api/input/survey_series/create

Create a feedback group

create

POST

/api/input/survey/create

Create a data source

create

POST

/api/input/survey/publish

Publish a data source

create

POST

/api/input/content/push

Push content to one question

push

POST

/api/input/content/push/bulk

Push content to multiple questions

push

List Data Sources

Retrieve all feedback groups and data sources your API key can access. Run this first to get the IDs you need for pushing content.

GET /api/input/surveys/list

Query Parameters

Parameter

Type

Description

survey_series_id

integer

Filter to specific feedback group

survey_id

integer

Filter to specific data source

Response

{
  "survey_series": [
    {
      "id": 123,
      "name": "Customer Feedback Q1",
      "surveys": [
        {
          "id": 456,
          "title": "Support Tickets",
          "description": "Imported from Zendesk",
          "mode": "ACCESSIBLE",
          "questions": [
            {
              "id": 789,
              "title": "Ticket Content",
              "type": "long_answer",
              "accepts_text": true
            },
            {
              "id": 790,
              "title": "Satisfaction Score",
              "type": "nps",
              "accepts_text": false
            }
          ]
        }
      ]
    }
  ],
  "org_id": 1
}

Understanding the Response

Field

Description

survey_series

Array of feedback groups

surveys

Array of data sources within a group

questions

Fields available for content

accepts_text

Important! Only push text to questions where this is true

mode

ACCESSIBLE = published, EDITING = draft

Example

curl -X GET "https://api.boundary-ai.com/api/input/surveys/list" \
  -H "Authorization: Bearer $API_KEY"

Push Content

Push feedback text to a specific question. This is the primary endpoint for importing data.

POST /api/input/content/push

Request Body

{
  "survey_series_id": "123",
  "survey_id": "456",
  "question": {
    "question_id": "789",
    "content": [
      "The checkout process was confusing",
      "Love the new dark mode feature!",
      "App crashes when uploading large files"
    ]
  },
  "source_reference": "zendesk-export-2024-01-15"
}

Parameters

Field

Type

Required

Description

survey_series_id

string

Yes

Feedback group ID

survey_id

string

Yes

Data source ID

question.question_id

string

Yes

Question ID (must have accepts_text: true)

question.content

array

Yes

Array of feedback strings

source_reference

string

Your reference for this import batch

Content Limits

Limit

Value

Max items per request

1,000

Max characters per item

10,000

Response

{
  "inserted": 3,
  "duplicates": 0,
  "aps_deducted": 3,
  "survey_series_id": 123,
  "survey_id": 456,
  "question_id": 789
}

Field

Description

inserted

Number of new entries added

duplicates

Number of duplicate entries skipped

aps_deducted

Analysis points consumed

Example: Python

import requests

API_KEY = "inpk_live_xxx_yyy"
BASE_URL = "https://api.boundary-ai.com"

response = requests.post(
    f"{BASE_URL}/api/input/content/push",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "survey_series_id": "123",
        "survey_id": "456",
        "question": {
            "question_id": "789",
            "content": [
                "Great product, easy to use!",
                "Support team was very helpful",
                "Would recommend to others"
            ]
        },
        "source_reference": "crm-export-2024-01"
    }
)

result = response.json()
print(f"Inserted: {result['inserted']}, APS used: {result['aps_deducted']}")

Example: JavaScript

const API_KEY = 'inpk_live_xxx_yyy';
const BASE_URL = 'https://api.boundary-ai.com';

const response = await fetch(`${BASE_URL}/api/input/content/push`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    survey_series_id: '123',
    survey_id: '456',
    question: {
      question_id: '789',
      content: [
        'Great product, easy to use!',
        'Support team was very helpful',
        'Would recommend to others'
      ]
    },
    source_reference: 'crm-export-2024-01'
  })
});

const result = await response.json();
console.log(`Inserted: ${result.inserted}, APS used: ${result.aps_deducted}`);

Example: cURL

curl -X POST "https://api.boundary-ai.com/api/input/content/push" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-001" \
  -d '{
    "survey_series_id": "123",
    "survey_id": "456",
    "question": {
      "question_id": "789",
      "content": [
        "Great product, easy to use!",
        "Support team was very helpful"
      ]
    }
  }'

Bulk Push Content

Push content to multiple questions in a single request. Useful when your data has multiple fields.

POST /api/input/content/push/bulk

Request Body

{
  "survey_series_id": "123",
  "survey_id": "456",
  "questions": [
    {
      "question_id": "789",
      "content": ["Feedback for question 1", "More feedback"]
    },
    {
      "question_id": "790",
      "content": ["Feedback for question 2"]
    }
  ],
  "source_reference": "bulk-import-001"
}

Parameters

Field

Type

Required

Description

survey_series_id

string

Yes

Feedback group ID

survey_id

string

Yes

Data source ID

questions

array

Yes

Array of question objects (max 100)

questions[].question_id

string

Yes

Question ID

questions[].content

array

Yes

Array of feedback strings

source_reference

string

Your reference for this batch

Response

{
  "total_inserted": 3,
  "total_duplicates": 0,
  "total_aps_deducted": 3,
  "results": [
    {"question_id": 789, "inserted": 2, "duplicates": 0},
    {"question_id": 790, "inserted": 1, "duplicates": 0}
  ]
}

Create Feedback Group

Create a new feedback group to organize related data sources.

POST /api/input/survey_series/create

Required Permission: create or all

Request Body

{
  "name": "Product Feedback 2024"
}

Parameters

Field

Type

Required

Description

name

string

Yes

Group name (2-255 characters)

Response

{
  "status": "success",
  "created": true,
  "survey_series": {
    "id": 123,
    "name": "Product Feedback 2024"
  }
}

Note: If a group with the same name exists, it returns the existing group with "created": false.

Create Data Source

Create a new data source with questions within a feedback group.

POST /api/input/survey/create

Required Permission: create or all

Request Body

{
  "survey_series_id": "123",
  "survey_title": "Zendesk Tickets Import",
  "survey_description": "Support tickets from January 2024",
  "questions": [
    {
      "question_title": "Ticket Content",
      "question_type": "DEPTH_TEXT",
      "is_mandatory": true
    },
    {
      "question_title": "Customer Sentiment",
      "question_type": "SCQ",
      "question_options": ["Positive", "Neutral", "Negative"],
      "is_mandatory": false
    }
  ]
}

Parameters

Field

Type

Required

Description

survey_series_id

string

Yes

Parent feedback group ID

survey_title

string

Yes

Data source name (1-100 chars)

survey_description

string

Description (max 1000 chars)

questions

array

Array of questions to create

Question Types

Type

Aliases

Description

Accepts Text

DEPTH_TEXT

long_answer

Long-form text (AI-analyzed)

✅ Yes

TEXT

short_answer

Short text

✅ Yes

MCQ

mcq

Multiple choice (multi-select)

❌ No

SCQ

scq

Single choice

❌ No

RATING

rating

1-5 scale

❌ No

NPS

nps

Net Promoter Score (0-10)

❌ No

Tip: Use DEPTH_TEXT for feedback text you want AI to analyze.

Response

{
  "status": "success",
  "survey_series_id": 123,
  "survey_id": 456,
  "questions_created": 2,
  "questions": [
    {"id": 789, "title": "Ticket Content", "type": "DEPTH_TEXT"},
    {"id": 790, "title": "Customer Sentiment", "type": "SCQ"}
  ],
  "message": "Survey 'Zendesk Tickets Import' created with 2 question(s)"
}

Publish Data Source

Publish a data source to enable data collection and analysis.

POST /api/input/survey/publish

Required Permission: create or all

Request Body

{
  "survey_series_id": 123,
  "survey_id": 456
}

Response

{
  "status": "success",
  "survey_id": 456,
  "survey_series_id": 123,
  "mode": "ACCESSIBLE",
  "message": "Survey published successfully"
}

Note: You must publish a data source before you can push content to it.

Webhooks

See Webhooks page

Complete Example

Here's a full workflow: create a feedback group, add a data source, publish it, and push content.

#!/bin/bash
# Full API workflow example

API_KEY="inpk_live_xxx_yyy"
BASE_URL="https://api.boundary-ai.com"

# Step 1: Create a feedback group
echo "Creating feedback group..."
SERIES_RESPONSE=$(curl -s -X POST "$BASE_URL/api/input/survey_series/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Tickets Q1 2024"}')

SERIES_ID=$(echo $SERIES_RESPONSE | jq -r '.survey_series.id')
echo "Created feedback group ID: $SERIES_ID"

# Step 2: Create a data source with a text question
echo "Creating data source..."
SURVEY_RESPONSE=$(curl -s -X POST "$BASE_URL/api/input/survey/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"survey_series_id\": \"$SERIES_ID\",
    \"survey_title\": \"Zendesk Import\",
    \"questions\": [
      {\"question_title\": \"Ticket Content\", \"question_type\": \"DEPTH_TEXT\"}
    ]
  }")

SURVEY_ID=$(echo $SURVEY_RESPONSE | jq -r '.survey_id')
QUESTION_ID=$(echo $SURVEY_RESPONSE | jq -r '.questions[0].id')
echo "Created data source ID: $SURVEY_ID, Question ID: $QUESTION_ID"

# Step 3: Publish the data source
echo "Publishing data source..."
curl -s -X POST "$BASE_URL/api/input/survey/publish" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"survey_series_id\": $SERIES_ID, \"survey_id\": $SURVEY_ID}"

# Step 4: Push feedback content
echo "Pushing content..."
PUSH_RESPONSE=$(curl -s -X POST "$BASE_URL/api/input/content/push" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: zendesk-batch-$(date +%Y%m%d)-001" \
  -d "{
    \"survey_series_id\": \"$SERIES_ID\",
    \"survey_id\": \"$SURVEY_ID\",
    \"question\": {
      \"question_id\": \"$QUESTION_ID\",
      \"content\": [
        \"The checkout process was confusing and I gave up\",
        \"Love the new search feature - so much faster!\",
        \"App crashes every time I try to upload a PDF\",
        \"Customer support resolved my issue within an hour\",
        \"Would be great to have dark mode option\"
      ]
    },
    \"source_reference\": \"zendesk-export-2024-01-15\"
  }")

echo "Push result: $PUSH_RESPONSE"
echo ""
echo "Done! View your feedback in the BoundaryAI dashboard."

Support

Email: hello@boundary-ai.com
Documentation: docs.boundary-ai.com
Dashboard: app.boundary-ai.com

PreviousUpdating Settings NextWebhooks

Last updated 10 days ago

hashtagOverview

hashtagCore Concepts

hashtagHow It Works

hashtagAuthentication

hashtagAPI Keys

hashtagKey Format

hashtagKey Permissions

hashtagGetting Your API Key

hashtagSecurity Notes

hashtagMaking Requests

hashtagBase URLs

hashtagRequest Format

hashtagResponse Format

hashtagSuccess Response

hashtagError Response

hashtagRate Limiting

hashtagIdempotency

hashtagEndpoints Reference

hashtagQuick Reference

hashtagList Data Sources

hashtagQuery Parameters

hashtagResponse

hashtagUnderstanding the Response

hashtagExample

hashtagPush Content

hashtagRequest Body

hashtagParameters

hashtagContent Limits

hashtagResponse

hashtagExample: Python

hashtagExample: JavaScript

hashtagExample: cURL

hashtagBulk Push Content

hashtagRequest Body

hashtagParameters

hashtagResponse

hashtagCreate Feedback Group

hashtagRequest Body

hashtagParameters

hashtagResponse

hashtagCreate Data Source

hashtagRequest Body

hashtagParameters

hashtagQuestion Types

hashtagResponse

hashtagPublish Data Source

hashtagRequest Body

hashtagResponse

hashtagWebhooks

hashtagComplete Example

hashtagSupport

Overview

Core Concepts

How It Works

Authentication

API Keys

Key Format

Key Permissions

Getting Your API Key

Security Notes

Making Requests

Base URLs

Request Format

Response Format

Success Response

Error Response

Rate Limiting

Idempotency

Endpoints Reference

Quick Reference

List Data Sources

Query Parameters

Response

Understanding the Response

Example

Push Content

Request Body

Parameters

Content Limits

Response

Example: Python

Example: JavaScript

Example: cURL

Bulk Push Content

Request Body

Parameters

Response

Create Feedback Group

Request Body

Parameters

Response

Create Data Source

Request Body

Parameters

Question Types

Response

Publish Data Source

Request Body

Response

Webhooks

Complete Example

Support