Agent700 API Alignment Data Guide

Overview

The Agent700 Platform API provides an Alignment Data system that allows you to store and manage custom key-value data that can be dynamically injected into AI agent prompts and system messages. This feature enables you to personalize agents with company-specific information, policies, settings, and other contextual data without modifying agent configurations.

Alignment data is particularly useful for:

Personalization: Inject user-specific or company-specific information into agent responses
Policy Management: Store and reference company policies, terms of service, and guidelines
Configuration: Maintain dynamic settings that can be updated without changing agent code
Context Injection: Provide relevant context to agents based on conversation topics

Base URL: https://api.agent700.ai/api

Important: Alignment data is a paid feature and requires a valid paid account subscription.

Alignment Data Concepts

What is Alignment Data?

Alignment data is a secure, user-scoped key-value storage system that allows you to store arbitrary data (strings, numbers, objects, arrays) associated with keys. These values can then be referenced in agent system messages using placeholder syntax, and the API will automatically replace them with the stored values when processing chat requests.

Key Features

User-Scoped: Each user's alignment data is isolated and private
Encrypted Storage: Values are encrypted at rest for security
Dot Notation Support: Keys can use dot notation (e.g., policy.privacy.statement) to represent nested structures
Dynamic Injection: Values are automatically injected into agent prompts using placeholder syntax
Pattern Matching: Query alignment data using wildcard patterns
JSON Construction: Automatically construct nested JSON objects from flat key-value pairs
Smart Document Evaluation: For large alignment data (>10,000 characters), use embeddings-based retrieval for relevant context

How It Works

Storage: Store key-value pairs using the alignment data API endpoints
Placeholders: Reference stored data in agent system messages using {{key}} syntax
Injection: When a chat request is made, the API automatically:
- Loads all alignment data for the user
- Replaces placeholders in system messages with actual values
- For large values, optionally uses embeddings to retrieve only relevant chunks

Placeholder Syntax

Alignment data placeholders use double curly braces with the key name:

{{key}}
{{company.name}}
{{policy.privacy.statement}}

Rules:

Placeholders must use double curly braces: {{ and }}
Keys can contain: letters, numbers, dots (.), dashes (-), and underscores (_)
Whitespace around the key is ignored: {{ key }} is equivalent to {{key}}
Placeholders are case-sensitive

Data Models

AlignmentData Schema

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "660e8400-e29b-41d4-a716-446655440001",
  "key": "company_name",
  "value": "Acme Corporation",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Fields:

id (string, UUID): Unique identifier for the alignment data record
userId (string, UUID): Owner of the alignment data (automatically set)
key (string, required): The key identifier (max 255 characters)
value (string, required): The stored value (can be JSON-encoded)
updatedAt (string, ISO 8601): Last update timestamp

Note: The value field is stored as a string but can contain JSON-encoded content. When using the construct-json endpoints, JSON strings are automatically parsed.

AlignmentDataUpsertRequest Schema

{
  "key": "company_name",
  "value": "Acme Corporation"
}

Fields:

key (string, required): The key identifier
value (string, required): The value to store (can be any JSON-serializable type)

AlignmentDataUpdateRequest Schema

{
  "key": "new_key",
  "value": "Updated value",
  "oldKey": "old_key"
}

Fields:

key (string, required): The new key (or existing key if not renaming)
value (string, required): The updated value
oldKey (string, optional): The existing key to rename from (if renaming)

API Endpoints

List All Alignment Data

Endpoint: GET /api/alignment-data

Description: Returns all alignment data records for the authenticated user, ordered by most recently updated first.

Authentication: Required (JWT Bearer Token or App Password)

Payment Required: Yes

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "660e8400-e29b-41d4-a716-446655440001",
    "key": "company_name",
    "value": "Acme Corporation",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "userId": "660e8400-e29b-41d4-a716-446655440001",
    "key": "policy.privacy.statement",
    "value": "We respect your privacy...",
    "updatedAt": "2024-01-16T14:22:00Z"
  }
]

Example Request:

curl -X GET "https://api.agent700.ai/api/alignment-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Alignment Data by Key

Endpoint: GET /api/alignment-data/by-key/{key}

Description: Returns a single alignment data record identified by the specified key.

Authentication: Required (JWT Bearer Token or App Password)

Payment Required: Yes

Path Parameters:

key (string, required): The key to retrieve

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "660e8400-e29b-41d4-a716-446655440001",
  "key": "company_name",
  "value": "Acme Corporation",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Error Responses:

404 Not Found: Key does not exist

Example Request:

curl -X GET "https://api.agent700.ai/api/alignment-data/by-key/company_name" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Create or Update Alignment Data (Upsert)

Endpoint: POST /api/alignment-data

Description: Creates a new alignment data record or updates an existing record if a record with the same key already exists. This is an "upsert" operation (update or insert).

Authentication: Required (JWT Bearer Token or App Password)

Payment Required: Yes

Request Body:

{
  "key": "company_name",
  "value": "Acme Corporation"
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "660e8400-e29b-41d4-a716-446655440001",
  "key": "company_name",
  "value": "Acme Corporation",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Error Responses:

400 Bad Request: Missing key or value

Example Request:

curl -X POST "https://api.agent700.ai/api/alignment-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "company_name",
    "value": "Acme Corporation"
  }'

Notes:

If a record with the key exists, it will be updated
If no record exists, a new one will be created
The updatedAt timestamp is automatically set

Update or Rename Alignment Data

Endpoint: PUT /api/alignment-data

Description: Updates an existing alignment data record. Can update the value or rename the key (or both). Unlike POST, this endpoint requires the key to already exist (unless renaming with oldKey).

Authentication: Required (JWT Bearer Token or App Password)

Payment Required: Yes

Request Body:

{
  "key": "new_key",
  "value": "Updated value",
  "oldKey": "old_key"
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "userId": "660e8400-e29b-41d4-a716-446655440001",
  "key": "new_key",
  "value": "Updated value",
  "updatedAt": "2024-01-20T14:22:00Z"
}

Error Responses:

400 Bad Request: Missing key/value, or new key already exists (when renaming)
404 Not Found: Key (or oldKey) not found

Example Requests:

Update value only:

curl -X PUT "https://api.agent700.ai/api/alignment-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "company_name",
    "value": "Updated Company Name"
  }'

Rename key:

curl -X PUT "https://api.agent700.ai/api/alignment-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "oldKey": "old_company_name",
    "key": "company_name",
    "value": "Acme Corporation"
  }'

Delete Alignment Data

Endpoint: DELETE /api/alignment-data/{key}

Description: Deletes an alignment data record by key.

Authentication: Required (JWT Bearer Token or App Password)

Payment Required: Yes

Path Parameters:

key (string, required): The key to delete

Response: 204 No Content (empty body)

Error Responses:

404 Not Found: Key does not exist

Example Request:

curl -X DELETE "https://api.agent700.ai/api/alignment-data/company_name" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Construct Nested JSON

Endpoint: GET /api/alignment-data/construct-json

Description: Constructs and returns a nested JSON object from all alignment data records. Keys using dot notation (e.g., policy.privacy.statement) are automatically converted into nested structures.

Authentication: Required (JWT Bearer Token or App Password)

Payment Required: Yes

Response:

{
  "company": {
    "name": "Acme Corporation"
  },
  "policy": {
    "privacy": {
      "statement": "We respect your privacy..."
    },
    "terms": {
      "acceptance": "By using this service..."
    }
  },
  "settings": {
    "theme": "dark",
    "notifications": true
  }
}

Example Request:

curl -X GET "https://api.agent700.ai/api/alignment-data/construct-json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

How It Works:

Keys with dot notation are split and nested: policy.privacy.statement → policy.privacy.statement
JSON-encoded values are automatically parsed
Flat keys remain at the root level

Construct JSON by Pattern

Endpoint: GET /api/alignment-data/by-pattern/{pattern}/construct-json

Description: Constructs nested JSON from alignment data records whose keys match a given pattern. Supports wildcard matching using *.

Authentication: Required (JWT Bearer Token or App Password)

Payment Required: Yes

Path Parameters:

pattern (string, required): Pattern to match (supports * wildcard)

Response:

{
  "policy": {
    "privacy": {
      "statement": "We respect your privacy..."
    },
    "terms": {
      "acceptance": "By using this service..."
    }
  }
}

Pattern Examples:

policy.* - Matches all keys starting with policy.
*.privacy.* - Matches all keys containing .privacy.
company.* - Matches all keys starting with company.

Example Request:

curl -X GET "https://api.agent700.ai/api/alignment-data/by-pattern/policy.*/construct-json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

List Key-Value Pairs by Pattern

Endpoint: GET /api/alignment-data/by-pattern/{pattern}

Description: Returns raw key-value pairs whose keys match a given pattern. Unlike construct-json, this returns a flat object with string keys and values.

Authentication: Required (JWT Bearer Token or App Password)

Payment Required: Yes

Path Parameters:

pattern (string, required): Pattern to match (supports * wildcard)

Response:

{
  "policy.privacy.statement": "We respect your privacy...",
  "policy.terms.acceptance": "By using this service..."
}

Example Request:

curl -X GET "https://api.agent700.ai/api/alignment-data/by-pattern/policy.*" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Using Alignment Data in Chat Requests

Basic Usage

Alignment data is automatically loaded and injected into agent system messages when you make chat requests. Simply include placeholders in your agent's system message (master prompt), and the API will replace them with the corresponding alignment data values.

Example System Message:

You are a helpful assistant for {{company_name}}.

Company Policy: {{policy.privacy.statement}}

When responding, always refer to our company as {{company_name}}.

When a chat request is made, the API will:

Load all alignment data for the authenticated user
Replace {{company_name}} with the stored value
Replace {{policy.privacy.statement}} with the stored value
Send the processed system message to the LLM

Smart Document Evaluation

For alignment data values larger than 10,000 characters, the API can use embeddings-based retrieval to inject only the most relevant portions of the content. This is controlled by the smartDocEvaluation parameter in chat requests.

When to Use:

Large policy documents (>10,000 characters)
Extensive knowledge bases
Long-form content that may not be fully relevant to every query

Chat Request Parameters:

smartDocEvaluation (boolean): Enable smart document evaluation
smartDocChunkSize (integer): Character size for text chunks
smartDocChunkOverlap (integer): Overlap between chunks
smartDocEmbeddingModel (string): Embedding model to use
smartDocTopK (integer): Number of top relevant chunks to retrieve

How It Works:

Alignment data values >10,000 characters are indexed using embeddings
When a chat request is made, the user query is embedded
The most relevant chunks are retrieved using similarity search
Only the relevant chunks are injected into the system message

Example Chat Request:

{
  "agentId": "agent-uuid",
  "messages": [
    {
      "role": "user",
      "content": "What is your privacy policy?"
    }
  ],
  "smartDocEvaluation": true,
  "smartDocChunkSize": 1000,
  "smartDocChunkOverlap": 200,
  "smartDocEmbeddingModel": "text-embedding-ada-002",
  "smartDocTopK": 3
}

Full Document Analysis

For comprehensive analysis of alignment data, you can use full document analysis mode. This processes all alignment data placeholders by chunking them and analyzing each chunk separately.

Chat Request Parameters:

fullDocAnalysis (boolean): Enable full document analysis
fullDocChunkSize (integer): Character size for text chunks
fullDocChunkOverlap (integer): Overlap between chunks
fullDocMaxLength (integer): Maximum total length of text to analyze

Note: Full document analysis does not support streaming responses.

Key Naming Conventions

Recommended Patterns

Flat Keys (simple values):

company_name
user_email
support_phone

Nested Keys (using dot notation):

company.name
company.address.street
company.address.city
policy.privacy.statement
policy.terms.acceptance
settings.theme
settings.notifications.enabled

Best Practices

Use lowercase with underscores or dots: company_name or company.name
Group related data: Use prefixes like company., policy., settings.
Be consistent: Choose a naming convention and stick to it
Avoid special characters: Only use letters, numbers, dots, dashes, and underscores
Keep keys descriptive: company_name is better than cn

Key Structure Examples

Company Information:

company.name
company.address.street
company.address.city
company.address.zip
company.phone
company.email

Policies:

policy.privacy.statement
policy.terms.acceptance
policy.refund.policy
policy.shipping.domestic
policy.shipping.international

Settings:

settings.theme
settings.language
settings.timezone
settings.notifications.email
settings.notifications.sms

Code Examples

Python Example

import requests

BASE_URL = "https://api.agent700.ai/api"
TOKEN = "your_jwt_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Create alignment data
def create_alignment_data(key, value):
    response = requests.post(
        f"{BASE_URL}/alignment-data",
        headers=headers,
        json={"key": key, "value": value}
    )
    return response.json()

# Get alignment data
def get_alignment_data():
    response = requests.get(
        f"{BASE_URL}/alignment-data",
        headers=headers
    )
    return response.json()

# Get by key
def get_by_key(key):
    response = requests.get(
        f"{BASE_URL}/alignment-data/by-key/{key}",
        headers=headers
    )
    return response.json()

# Update alignment data
def update_alignment_data(key, value):
    response = requests.put(
        f"{BASE_URL}/alignment-data",
        headers=headers,
        json={"key": key, "value": value}
    )
    return response.json()

# Delete alignment data
def delete_alignment_data(key):
    response = requests.delete(
        f"{BASE_URL}/alignment-data/{key}",
        headers=headers
    )
    return response.status_code == 204

# Construct nested JSON
def construct_json():
    response = requests.get(
        f"{BASE_URL}/alignment-data/construct-json",
        headers=headers
    )
    return response.json()

# Example usage
create_alignment_data("company_name", "Acme Corporation")
create_alignment_data("policy.privacy.statement", "We respect your privacy...")

# Use in chat request
chat_response = requests.post(
    f"{BASE_URL}/chat",
    headers=headers,
    json={
        "agentId": "your-agent-id",
        "messages": [
            {"role": "user", "content": "Tell me about your company"}
        ]
    }
)

JavaScript/TypeScript Example

const BASE_URL = "https://api.agent700.ai/api";
const TOKEN = "your_jwt_token";

const headers = {
  Authorization: `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};

// Create or update alignment data
async function upsertAlignmentData(key: string, value: string) {
  const response = await fetch(`${BASE_URL}/alignment-data`, {
    method: "POST",
    headers,
    body: JSON.stringify({ key, value }),
  });
  return response.json();
}

// Get all alignment data
async function getAllAlignmentData() {
  const response = await fetch(`${BASE_URL}/alignment-data`, {
    headers,
  });
  return response.json();
}

// Get by key
async function getAlignmentDataByKey(key: string) {
  const response = await fetch(`${BASE_URL}/alignment-data/by-key/${key}`, {
    headers,
  });
  return response.json();
}

// Update alignment data
async function updateAlignmentData(
  key: string,
  value: string,
  oldKey?: string
) {
  const response = await fetch(`${BASE_URL}/alignment-data`, {
    method: "PUT",
    headers,
    body: JSON.stringify({ key, value, oldKey }),
  });
  return response.json();
}

// Delete alignment data
async function deleteAlignmentData(key: string) {
  const response = await fetch(`${BASE_URL}/alignment-data/${key}`, {
    method: "DELETE",
    headers,
  });
  return response.status === 204;
}

// Construct nested JSON
async function constructAlignmentJSON() {
  const response = await fetch(`${BASE_URL}/alignment-data/construct-json`, {
    headers,
  });
  return response.json();
}

// Example usage
await upsertAlignmentData("company_name", "Acme Corporation");
await upsertAlignmentData("policy.privacy.statement", "We respect your privacy...");

// Use in chat request
const chatResponse = await fetch(`${BASE_URL}/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    agentId: "your-agent-id",
    messages: [
      { role: "user", content: "Tell me about your company" },
    ],
  }),
});

cURL Examples

Create alignment data:

curl -X POST "https://api.agent700.ai/api/alignment-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "company_name",
    "value": "Acme Corporation"
  }'

Get all alignment data:

curl -X GET "https://api.agent700.ai/api/alignment-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get by key:

curl -X GET "https://api.agent700.ai/api/alignment-data/by-key/company_name" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update alignment data:

curl -X PUT "https://api.agent700.ai/api/alignment-data" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "company_name",
    "value": "Updated Company Name"
  }'

Delete alignment data:

curl -X DELETE "https://api.agent700.ai/api/alignment-data/company_name" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Construct nested JSON:

curl -X GET "https://api.agent700.ai/api/alignment-data/construct-json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Use Cases and Patterns

Use Case: Company Information Injection

Store company-specific information and inject it into agent responses.

Setup:

{
  "key": "company.name",
  "value": "Acme Corporation"
}

{
  "key": "company.industry",
  "value": "Technology"
}

Agent System Message:

You are a customer service representative for {{company.name}}, 
a leading company in the {{company.industry}} industry.

Use Case: Policy and Compliance

Store policy documents and reference them in agent responses.

Setup:

{
  "key": "policy.privacy.statement",
  "value": "We respect your privacy and are committed to protecting your personal data..."
}

{
  "key": "policy.refund.policy",
  "value": "We offer a 30-day money-back guarantee on all products..."
}

Agent System Message:

When customers ask about privacy, reference: {{policy.privacy.statement}}

When customers ask about refunds, reference: {{policy.refund.policy}}

Use Case: Multi-Tenant Configuration

Use alignment data to configure agents for different tenants or organizations.

Setup:

{
  "key": "tenant.branding.logo_url",
  "value": "https://example.com/logo.png"
}

{
  "key": "tenant.settings.primary_color",
  "value": "#FF5733"
}

Use Case: Dynamic Content Updates

Update agent behavior without modifying agent configurations.

Setup:

{
  "key": "promotions.current_offer",
  "value": "20% off all products this week!"
}

Agent System Message:

Current promotion: {{promotions.current_offer}}

When the promotion changes, simply update the alignment data value.

Version Your Alignment Data

Consider including version information in keys for major updates:

policy.privacy.v2.statement
policy.privacy.v1.statement (deprecated)

Validate Placeholder Usage

Before deploying agents, verify that all placeholders in system messages have corresponding alignment data:

# Example validation function
def validate_placeholders(system_message, alignment_data):
    import re
    pattern = r"\{\{\s*([-a-zA-Z0-9._]+)\s*\}\}"
    placeholders = re.findall(pattern, system_message)
    missing = [p for p in placeholders if p not in alignment_data]
    if missing:
        raise ValueError(f"Missing alignment data for: {missing}")
    return True

Handle Missing Placeholders Gracefully

If a placeholder doesn't have a corresponding value, it will remain as {{key}} in the system message. Consider:

Providing default values in your application code
Validating alignment data before making chat requests
Using conditional logic in system messages when possible

Secure Sensitive Data

While alignment data is encrypted at rest, be cautious about storing:

Passwords or API keys
Personal identifiable information (PII) unless necessary
Financial information

Use Pattern Matching for Bulk Operations

When working with related alignment data, use pattern matching:

8. Use Pattern Matching for Bulk Operations

When working with related alignment data, use pattern matching:

# Get all policy-related alignment data
policy_data = requests.get(
    f"{BASE_URL}/alignment-data/by-pattern/policy.*/construct-json",
    headers=headers
).json()

9. Monitor Alignment Data Usage

Regularly review your alignment data to:

Remove unused keys
Update outdated values
Consolidate duplicate information

10. Test Placeholder Replacement

Test your agents with various alignment data configurations to ensure placeholders are replaced correctly.

Troubleshooting

Placeholder Not Replaced

Symptom: Placeholder remains as {{key}} in the agent response.

Possible Causes:

Alignment data doesn't exist for the key
Key name mismatch (case-sensitive, typo)
User doesn't have access to the alignment data

Solutions:

Verify the key exists: GET /api/alignment-data/by-key/{key}
Check for typos and case sensitivity
Verify you're authenticated as the correct user

Large Alignment Data Not Working

Symptom: Very large alignment data values cause errors or poor performance.

Solutions:

Enable smart document evaluation: smartDocEvaluation: true
Adjust chunk size and overlap parameters
Consider splitting large values into multiple keys

Pattern Matching Not Working

Symptom: Pattern queries return no results.

Possible Causes:

Incorrect wildcard syntax
No keys match the pattern

Solutions:

Use * for wildcards (not % or other characters)
Verify keys exist that match the pattern
Test with a simpler pattern first (e.g., policy.*)

JSON Construction Issues

Symptom: Constructed JSON doesn't match expected structure.

Possible Causes:

Invalid JSON in values
Conflicting keys at different nesting levels

Solutions:

Ensure JSON-encoded values are valid JSON
Avoid conflicts like company.name and company (one is a string, one is an object)

Authentication Errors

Symptom: 401 Unauthorized errors.

Solutions:

Verify your JWT token is valid and not expired
Check that you're using the correct authentication header format: Bearer {token}
Ensure your account has a paid subscription (alignment data requires payment)

Payment Required Errors

Symptom: 402 Payment Required or similar errors.

Solutions:

Verify your account has an active paid subscription
Contact support if you believe you should have access

Key Already Exists

Symptom: 400 Bad Request with "Key already exists" when trying to rename.

Solutions:

Use POST (upsert) instead of PUT if you want to update existing keys
Delete the existing key first if you want to rename
Check for the key: GET /api/alignment-data/by-key/{key}

Value Not Updating

Symptom: PUT request succeeds but value doesn't change.

Solutions:

Verify you're using the correct key
Check the response to confirm the update
Use POST (upsert) for simpler updates

Additional Resources

Agent700 API Authentication Guide - Learn about authentication methods
Agent700 API Workflows Guide - Learn about workflow management
Agent700 API Error Handling Guide - Comprehensive error handling reference
OpenAPI Specification - Complete API specification

Summary

Alignment data is a powerful feature that enables dynamic content injection into AI agents. Key takeaways:

Storage: Secure, encrypted key-value storage per user
Injection: Automatic placeholder replacement in system messages
Flexibility: Support for nested structures via dot notation
Performance: Smart document evaluation for large content
Organization: Pattern matching and JSON construction for bulk operations

By following the best practices and patterns outlined in this guide, you can effectively use alignment data to create personalized, context-aware AI agents that adapt to your specific needs without requiring agent configuration changes.