API Reference Overview

This guide provides a comprehensive overview of the Maitento REST API, covering authentication, all available endpoints organized by domain, common patterns, and detailed usage information for each API category.

Table of Contents

1. API Overview
2. Authentication
3. Common Patterns
4. Authentication Endpoints
5. User Management
6. Tenant and Namespace Management
7. File System Operations
8. Build and Deploy Operations
9. Process Management
10. Invitations
11. Quick Reference Tables

API Overview

The Maitento API is a RESTful HTTP API that provides programmatic access to all platform capabilities. The API uses JSON for request and response bodies and follows standard HTTP conventions for methods, status codes, and headers.

Base URL

All API endpoints are accessed relative to your Maitento instance base URL:

https://api.maitento.com

Request Format

• Content-Type: application/json for most endpoints
• Character Encoding: UTF-8
• Date/Time Format: ISO 8601 (e.g., 2024-01-15T10:30:00Z)
• Identifiers: GUIDs (UUIDs) in standard format (e.g., 550e8400-e29b-41d4-a716-446655440000)

HTTP Methods

Authentication

Maitento supports two authentication mechanisms to accommodate different use cases.

JWT Bearer Authentication

JWT tokens are issued upon successful login and are ideal for web applications and interactive sessions.

Header Format:

Authorization: Bearer <jwt-token>

Token Characteristics:

• Algorithm: RSA SHA256 with X509 certificate signing
• Default lifetime: 24 hours (86400 seconds)
• Clock skew tolerance: 2 minutes
• Recommended refresh: At 80% of token lifetime

JWT Claims:

API Key Authentication

API keys provide persistent authentication for programmatic access without requiring interactive login. Ideal for CI/CD pipelines, integrations, and scripts.

Header Format:

Authorization: ApiKey <ClientId> <ClientSecret>

Where:

• ClientId is a GUID (user identifier)
• ClientSecret is the secret generated when creating the API key

Key Characteristics:

• Can have optional expiration dates
• Must be explicitly enabled
• Stored as SHA256 hash (secrets cannot be retrieved after creation)

Roles

Common Patterns

Standard Response Codes

Error Response Format

Validation Errors (400 Bad Request):

{
  "validationFailures": [
    {
      "memberName": "fieldName",
      "message": "Human-readable error message",
      "errorCode": "machine-readable-code"
    }
  ]
}

Standard HTTP Errors:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Error Title",
  "status": 400
}

Resource Addressing

Many resources support multiple addressing schemes:

By ID:

/resource/by-id/{id}

By Name (within namespace):

/namespaces/{namespaceName}/resource/by-name/{name}

Namespace-Qualified References

Resources can be referenced using namespace-qualified names:

resourceName@namespaceName

For example:

• my-agent@production - References the agent “my-agent” in the “production” namespace
• config-file@development - References the file “config-file” in the “development” namespace

Authentication Endpoints

Login

Authenticates a user with email and password credentials.

Endpoint: PUT /auth

Authentication: None required (public endpoint)

Request:

PUT /auth HTTP/1.1
Content-Type: application/json

{
  "emailAddress": "user@example.com",
  "password": "MySecureP@ssw0rd!"
}

Response:

{
  "authenticationToken": {
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires": "2024-01-15T14:30:00Z"
  },
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "dateCreated": "2023-06-01T10:00:00Z",
    "dateUpdated": "2024-01-14T14:30:00Z",
    "name": "John Doe",
    "emailAddress": "user@example.com",
    "isEnabled": true,
    "roles": ["Tenant.User"]
  },
  "tenantName": "Acme Corporation"
}

Renew Token

Refreshes an existing valid JWT token.

Endpoint: GET /auth/renew

Authentication: Required (Bearer only)

Request:

GET /auth/renew HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Response: Same as Login response with new token and extended expiration.

Token Refresh Best Practices

const tokenLifetimeMs = 24 * 60 * 60 * 1000; // 24 hours
const refreshThreshold = 0.8; // 80%

function shouldRefreshToken(tokenExpires) {
  const now = Date.now();
  const expiresAt = new Date(tokenExpires).getTime();
  const timeRemaining = expiresAt - now;
  return timeRemaining < (tokenLifetimeMs * (1 - refreshThreshold));
}

User Management

User Registration

Register a new user account using an invitation.

Endpoint: POST /users/register

Authentication: None required (public endpoint)

Request:

{
  "acceptTermsAndConditions": true,
  "inviteId": "aa0e8400-e29b-41d4-a716-446655440005",
  "userName": "Jane Smith",
  "emailAddress": "jane.smith@example.com",
  "password": "Str0ngP@ssword!"
}

Password Requirements:

• Option 1: 8-15 characters with at least one lowercase, one uppercase, one digit, and one special character
• Option 2: 20+ characters as a passphrase (at least 4 words separated by spaces)

Email Verification

Verify a user’s email address after registration.

Endpoint: POST /users/self/verify-email-address

Request:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "activationKey": "verify-key-abc123"
}

Password Management

Initiate Password Reset:

PUT /users/self/password-reset
Content-Type: application/json

{
  "emailAddress": "user@example.com"
}

Complete Password Reset:

POST /users/self/password-reset
Content-Type: application/json

{
  "emailAddress": "user@example.com",
  "resetKey": "abc123-reset-key-xyz789",
  "password": "NewP@ssw0rd!"
}

Change Password (Authenticated):

PUT /users/self/password
Authorization: Bearer <token>
Content-Type: application/json

{
  "existingPassword": "OldP@ssw0rd!",
  "newPassword": "NewP@ssw0rd!"
}

API Key Management

List API Keys:

GET /users/self/api-keys
Authorization: Bearer <token>

Create API Key:

POST /users/self/api-keys
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "CI/CD Pipeline Key",
  "dateExpires": "2025-12-31T23:59:59Z"
}

Response:

{
  "id": "990e8400-e29b-41d4-a716-446655440004",
  "secret": "maitento_sk_live_abc123xyz789..."
}

Important: The secret value is only returned at creation time. Store it securely.

Delete API Key:

DELETE /users/self/api-keys/by-id/{id}
Authorization: Bearer <token>

User Administration (Admin Only)

List All Users:

GET /users
Authorization: Bearer <token>

Update User:

PUT /users/by-id/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "isAdmin": true,
  "isEnabled": true
}

Tenant and Namespace Management

Tenant Registration

Register a new tenant and create an admin user account.

Endpoint: POST /tenants/register

Authentication: None required (public endpoint)

Request:

{
  "acceptTermsAndConditions": true,
  "code": "INVITE2024ABC",
  "userName": "johndoe",
  "companyName": "Acme Corporation",
  "emailAddress": "john.doe@acme.com",
  "password": "SecureP@ss123"
}

Response:

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

Upon successful registration:

1. A new tenant is created
2. An admin user is created with the Tenant.Admin role
3. A verification email is sent
4. A new invitation code is generated (with 10 uses)

Namespace Management

Namespaces are logical containers for organizing and isolating resources within a tenant.

List All Namespaces:

GET /namespaces
Authorization: Bearer <token>

Get Namespace by ID:

GET /namespaces/by-id/{id}
Authorization: Bearer <token>

Get Namespace by Name:

GET /namespaces/by-name/{name}
Authorization: Bearer <token>

Create Namespace:

POST /namespaces
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "production"
}

Name Validation Rules:

• Minimum length: 1 character
• Maximum length: 128 characters
• Allowed characters: a-z, A-Z, 0-9, _, -, .
• Forbidden characters: @ (reserved for namespace-qualified references)
• Forbidden patterns: .., /, \ (path traversal prevention)

Update Namespace:

PUT /namespaces/by-id/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "production-v2"
}

Partitions

Partitions provide logical groupings for organizing ingested files and documents for vector search and RAG operations.

List All Partitions:

GET /partitions
Authorization: Bearer <token>

Get Partition by ID:

GET /partitions/by-id/{id}
Authorization: Bearer <token>

Create Partition:

PUT /partitions
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Engineering Documentation"
}

Delete Partition (Admin only):

DELETE /partitions/by-id/{id}
Authorization: Bearer <token>

Secrets Management

Secrets are secure key-value pairs for storing sensitive configuration data.

List All Secrets:

GET /secrets
Authorization: Bearer <token>

Create Secret:

POST /secrets
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "DATABASE_CONNECTION_STRING",
  "value": "Server=myserver;Database=mydb;..."
}

Get Secret Value:

GET /secrets/by-name/{name}/value
Authorization: Bearer <token>

Security Note: This endpoint returns the secret value in plain text. Use with caution.

Update Secret:

PUT /secrets/by-id/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "DATABASE_CONNECTION_STRING",
  "value": "Server=newserver;Database=newdb;..."
}

Delete Secret:

DELETE /secrets/by-id/{id}
Authorization: Bearer <token>

File System Operations

Virtual File System (VFS)

The VFS provides a managed, tenant-isolated file storage system with support for files, directories, and advanced operations.

VFS Management

List All VFS (Tenant-Wide):

GET /vfs
Authorization: Bearer <token>

List VFS in Namespace:

GET /namespaces/{namespaceName}/vfs
Authorization: Bearer <token>

Create VFS:

POST /namespaces/{namespaceName}/vfs
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "project-files"
}

Get VFS by ID:

GET /vfs/by-id/{id}
Authorization: Bearer <token>

Delete VFS:

DELETE /vfs/by-id/{id}
Authorization: Bearer <token>

Directory Operations

Create Directory:

PUT /vfs/by-id/{id}/directories?path=/src/components
Authorization: Bearer <token>

List Directory Contents:

GET /vfs/by-id/{id}/directories/contents?path=/src
Authorization: Bearer <token>

Check Directory Exists:

GET /vfs/by-id/{id}/directories/exists?path=/src/components
Authorization: Bearer <token>

Delete Directory:

DELETE /vfs/by-id/{id}/directories?path=/src/old&recursive=true
Authorization: Bearer <token>

File Operations

Check File Exists:

GET /vfs/by-id/{id}/files/exists?path=/src/index.ts
Authorization: Bearer <token>

Read File as Text:

GET /vfs/by-id/{id}/files/contents/text?path=/src/index.ts
Authorization: Bearer <token>

Read File as Lines:

GET /vfs/by-id/{id}/files/contents/lines?path=/src/index.ts
Authorization: Bearer <token>

Write Text to File:

PUT /vfs/by-id/{id}/files/write/text?path=/src/index.ts
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "import { App } from './app';\n\nconst app = new App();\napp.start();\n"
}

Append Text to File:

PUT /vfs/by-id/{id}/files/append/text?path=/logs/app.log
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "[2024-01-16T14:30:00Z] INFO: Application started\n"
}

Delete File:

DELETE /vfs/by-id/{id}/files?path=/src/old-file.ts
Authorization: Bearer <token>

Copy and Move Operations

Copy File or Directory:

PUT /vfs/by-id/{id}/copy?path=/src/index.ts&destination=/backup/index.ts
Authorization: Bearer <token>

Move File or Directory:

POST /vfs/by-id/{id}/move?path=/src/old-name.ts&destination=/src/new-name.ts
Authorization: Bearer <token>

Search and Navigation

Find Files:

POST /vfs/by-id/{id}/find
Authorization: Bearer <token>
Content-Type: application/json

{
  "pattern": "**/*.ts",
  "grep": "import.*React",
  "grepMode": "regex",
  "ignoreCase": true,
  "maxResults": 50
}

Supported Glob Patterns:

• * - Matches any characters except path separator
• ** - Matches any characters including path separator (recursive)
• ? - Matches any single character
• [abc] - Matches any character in brackets
• {a,b} - Matches any of the comma-separated patterns

Tree View:

POST /vfs/by-id/{id}/tree
Authorization: Bearer <token>
Content-Type: application/json

{
  "path": "/src",
  "maxDepth": 3,
  "includeFiles": true
}

Edit Operations

Edit File (Find/Replace):

POST /vfs/by-id/{id}/files/edit
Authorization: Bearer <token>
Content-Type: application/json

{
  "path": "/src/config.ts",
  "operations": [
    {
      "type": "replace",
      "find": "localhost:3000",
      "replace": "api.example.com",
      "replaceAll": true
    }
  ]
}

Edit File (Replace Lines):

{
  "path": "/src/app.ts",
  "operations": [
    {
      "type": "replaceLines",
      "startLine": 10,
      "endLine": 15,
      "content": "// New implementation\nfunction init() {\n  console.log('Initialized');\n}\n"
    }
  ]
}

Edit File (Insert After Line):

{
  "path": "/src/index.ts",
  "operations": [
    {
      "type": "insertAfter",
      "insertAfterLine": 0,
      "content": "// Copyright 2024 Example Corp\n"
    }
  ]
}

Batch Edit (Multiple Files):

POST /vfs/by-id/{id}/batch/edit
Authorization: Bearer <token>
Content-Type: application/json

{
  "edits": [
    {
      "path": "/src/config.ts",
      "operations": [
        {
          "type": "replace",
          "find": "development",
          "replace": "production",
          "replaceAll": true
        }
      ]
    },
    {
      "path": "/src/constants.ts",
      "operations": [
        {
          "type": "replace",
          "find": "DEBUG = true",
          "replace": "DEBUG = false"
        }
      ]
    }
  ],
  "atomic": true
}

Batch Read (Multiple Files):

POST /vfs/by-id/{id}/batch/read
Authorization: Bearer <token>
Content-Type: application/json

{
  "paths": [
    "/src/index.ts",
    "/src/app.ts",
    "/package.json"
  ],
  "maxLinesPerFile": 100
}

File Ingestion and RAG

The Files API provides file upload/ingestion and RAG capabilities including vector embeddings and semantic search.

File Upload

Upload File to Partition:

PUT /files/partitions/{partitionId}
Authorization: Bearer <token>
Content-Type: multipart/form-data

<file binary content>

Supported File Types:

• Documents: .docx, .pdf, .pptx, .xlsx
• Text: .txt, .md, .html, .csv, .json, .xml
• Images: .jpg, .jpeg, .png, .gif, .bmp, .webp

File Retrieval

Get File by Checksum:

GET /files/by-checksum/{checksum}
Authorization: Bearer <token>

Download File:

GET /files/by-id/{id}
Authorization: Bearer <token>

Get File Details:

GET /files/by-id/{id}/details
Authorization: Bearer <token>

Get Extracted Text:

GET /files/by-id/{id}/text
Authorization: Bearer <token>

Vector Embeddings and RAG

Generate Embeddings:

PUT /files/embeddings/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "text": "How do I configure the product for production use?"
}

Search Embeddings (RAG Search):

PUT /files/embeddings/search
Authorization: Bearer <token>
Content-Type: application/json

{
  "query": "How do I install the product on Windows?",
  "partitionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response:

[
  {
    "id": "f1e2d3c4-b5a6-9087-6543-210fedcba987",
    "name": "installation-guide.pdf",
    "contentType": "application/pdf",
    "size": 524288,
    "type": "Pdf",
    "text": "Windows Installation\n\nStep 1: Download the installer...",
    "score": 0.892
  }
]

Generate Chunks:

PUT /files/chunks-generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "text": "Long document text to be chunked..."
}

Build and Deploy Operations

The Build API provides a unified endpoint for compiling, validating, and deploying Maitento resources.

Build Resources

Endpoint: PUT /namespaces/{namespaceName}/build

Request Structure:

{
  "isDeploy": true,
  "agents": [
    {
      "name": "customer-support-agent",
      "filename": "customer-support.agent",
      "lines": ["agent CustomerSupport { ... }"]
    }
  ],
  "capsules": [],
  "connectors": {
    "openApi": [],
    "modelContextProtocol": []
  },
  "externalOperations": {
    "openApi": [],
    "modelContextProtocol": []
  },
  "interactions": {
    "oneShot": [],
    "roundRobin": [],
    "managed": [],
    "routed": []
  },
  "apps": [
    {
      "name": "my-app",
      "metadata": {
        "filename": "app.meta",
        "lines": ["..."]
      },
      "code": [
        {
          "filename": "main.cog",
          "lines": ["..."]
        }
      ]
    }
  ],
  "resourceFiles": {
    "prompts": [
      {
        "name": "prompts/customer-support.txt",
        "content": "You are a helpful customer support agent..."
      }
    ],
    "json": []
  }
}

Response:

{
  "isSuccess": true,
  "isDeployed": true,
  "log": [
    {
      "text": "Compiling agent 'customer-support-agent'",
      "date": "2024-03-15T10:30:00.123Z",
      "logLevel": "Info",
      "filename": "customer-support.agent",
      "lineNumber": null,
      "character": null
    }
  ],
  "agents": [
    {
      "mode": "Created",
      "entity": { /* Agent object */ }
    }
  ],
  "capsules": [],
  "connectors": { "openApi": [], "modelContextProtocol": [] },
  "externalOperations": { "openApi": [], "modelContextProtocol": [] },
  "interactions": { "roundRobin": [], "oneShot": [], "routed": [], "managed": [] },
  "apps": []
}

Build Entity Modes:

• Created - A new entity was created
• Updated - An existing entity was updated
• Unchanged - No changes detected

Log Levels:

• Debug - Diagnostic information
• Info - Build progress information
• Warning - Non-fatal issues
• Error - Fatal errors (causes isSuccess: false)

Validation-Only Build

Set isDeploy: false to validate resources without deploying:

{
  "isDeploy": false,
  "agents": [...],
  ...
}

Process Management

Kill Process

Terminates a running process immediately.

Endpoint: POST /processes/{processType}/{processId}/kill

Process Types:

• App - Application execution process
• Interaction - Conversational AI interaction process
• CodeGeneration - AI code generation process
• Capsule - Capsule execution process

Request:

POST /processes/App/a1b2c3d4-e5f6-7890-abcd-ef1234567890/kill
Authorization: Bearer <token>

Response: 204 No Content

Process Status Reference:

Invitations

Invitation Codes

List Invitation Codes:

GET /invitations/codes
Authorization: Bearer <token>

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenantId": "660e8400-e29b-41d4-a716-446655440001",
    "userCreatedById": "770e8400-e29b-41d4-a716-446655440002",
    "dateCreated": "2024-01-01T10:00:00Z",
    "dateUpdated": "2024-01-10T15:30:00Z",
    "code": "WELCOME2024",
    "countOriginal": 10,
    "countRemaining": 7
  }
]

Invites

Send Invite:

POST /invitations/invites
Authorization: Bearer <token>
Content-Type: application/json

{
  "invitationCodeId": "550e8400-e29b-41d4-a716-446655440000",
  "emailAddress": "newuser@example.com",
  "inviteToTenant": true
}

List Invites:

GET /invitations/invites
Authorization: Bearer <token>

Get Invite Summary (Public):

GET /invitations/invites/by-id/{id}/summary?emailAddress=newuser@example.com

Cancel Invite:

POST /invitations/invites/by-id/{id}/cancel
Authorization: Bearer <token>

Resend Invite Email:

POST /invitations/invites/by-id/{id}/resend-email
Authorization: Bearer <token>

Invite Status Values:

• Unused - Sent but not yet redeemed
• Cancelled - Cancelled by sender
• Used - Redeemed by recipient

Quick Reference Tables

Authentication Endpoints

User Endpoints

Tenant and Namespace Endpoints

Partition Endpoints

Secrets Endpoints

VFS Endpoints

Files Endpoints

Build Endpoints

Process Endpoints

Invitation Endpoints

Security Best Practices

1. Token Storage: Store JWT tokens securely (HttpOnly cookies for web apps, secure storage for mobile)
2. API Key Secrets: Store API key secrets securely; they cannot be retrieved after creation
3. HTTPS: Always use HTTPS in production to protect credentials in transit
4. Token Expiration: Implement proper token refresh logic to maintain sessions
5. API Key Expiration: Consider setting expiration dates on API keys for security
6. Secret Access: Use the value endpoint carefully; avoid logging secret values
7. Role-Based Access: Assign minimum necessary roles to users and API keys