Agency API

Manage your agency programmatically with our comprehensive API. Create subteams, manage users, and configure access controls.

API Key Required

You need an agency API key to use this endpoint. Agency owners can generate API keys from their settings.

Overview

The Agency API allows you to programmatically manage your agency's operations. Currently, we provide endpoints for creating and managing subteams. More endpoints for user management, billing, and analytics are coming soon.

Subteams API

Create and manage subteams for your agency with full control over access permissions and credit limits.

1. Endpoint

POST Request

POST /api/v1/agency/subteams

2. Authentication

Include your agency API key in the X-AGENCY-KEY header:

Header

X-AGENCY-KEY: your-api-key

3. Example Request

cURL Example

curl -X POST https://echo.win/api/v1/agency/subteams \
  -H "Content-Type: application/json" \
  -H "X-AGENCY-KEY: your-api-key" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "teamName": "John's Team",
    "email": "[email protected]",
    "totalMonthlyCredits": 1000,
    "accessConfig": {
      "users": true,
      "instructions": false,
      "instructionsWrite": false,
      "testing": true,
      "knowledgeBase": true,
      "agentConfiguration": false,
      "agentCreation": false
    }
  }'

Request Schema

Field	Type	Required	Description
firstName	string	✓	User's first name (1-50 characters)
lastName	string	✓	User's last name (1-50 characters)
teamName	string	✓	Name for the new subteam (1-50 characters)
email	string	✓	Valid email address for the team admin
totalMonthlyCredits	number	-	Monthly credit limit (default: 1000)
accessConfig	object	-	Access permissions configuration

Access Configuration

The accessConfig object controls what features the subteam can access:

users - User management capabilities
instructions - Read access to instructions
instructionsWrite - Write access to instructions
testing - Testing capabilities
knowledgeBase - Knowledge base access
agentConfiguration - Agent configuration access
agentCreation - Agent creation capabilities

Response Format

Success Response (201)

JSON Response

{
  "message": "Subteam created successfully",
  "subteam": {
    "agencyTeam": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "John's Team",
      "teamId": "987fcdeb-51a2-43d7-8fed-123456789abc",
      "totalMonthlyCredits": 1000,
      "accessConfig": {
        "users": true,
        "instructions": false,
        "instructionsWrite": false,
        "testing": true,
        "knowledgeBase": true,
        "agentConfiguration": false,
        "agentCreation": false
      }
    },
    "user": {
      "id": "user-uuid",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "verificationSent": false
    }
  }
}

Error Codes

401Missing API Key

The X-AGENCY-KEY header is missing from your request. Make sure to include your API key in the header.

403Invalid API Key

The provided API key is invalid or doesn't exist. Verify your API key is correct.

403Agency Not Found

The API key doesn't belong to an agency owner team. Only agency owners can create subteams.

400Validation Error

The request data is invalid. Check the error message for specific validation failures.

405Method Not Allowed

Only POST requests are allowed for this endpoint.

500Internal Server Error

An unexpected error occurred on the server. Please try again or contact support if the problem persists.