Skip to main content

API Reference Overview

DgiDgi One provides a comprehensive REST API for building multi-tenant AI-powered applications.

Base URL​

https://api.dgidgi.ai

Authentication​

All API requests require authentication using an API Key.

Pass your API key in the Authorization header. Keys always start with a prefix like chy_sdk_.

curl https://api.dgidgi.ai/api/v1/projects \
  -H "Authorization: Bearer chy_sdk_..."

For a detailed guide on key types (chy_sdk_, chy_ci_, etc.) and generation, see the Authentication Guide.

JWT Tokens​

Used internally for frontend clients. See Authentication for details.

Rate Limiting​

  • Default: 1000 requests per 60 seconds
  • Auth endpoints: No rate limiting
  • Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Response Format​

Success Response​

{
  "data": {
    "id": "proj_123",
    "name": "My Project",
    "created_at": "2026-01-07T18:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-07T18:00:00Z"
  }
}

Error Response​

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Project not found",
    "details": {
      "project_id": "proj_123"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-01-07T18:00:00Z"
  }
}

Error Codes​

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid authentication
FORBIDDEN403Insufficient permissions
RESOURCE_NOT_FOUND404Resource does not exist
VALIDATION_ERROR400Invalid request parameters
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error

Core Resources​

Projects​

Manage multi-tenant projects and workspaces.

# List projects
GET /api/v1/projects

# Create project
POST /api/v1/projects

# Get project
GET /api/v1/projects/:id

# Update project
PATCH /api/v1/projects/:id

# Delete project
DELETE /api/v1/projects/:id

AI Agents​

Create and manage AI agents.

# List agents
GET /api/v1/agents

# Create agent
POST /api/v1/agents

# Execute agent task
POST /api/v1/agents/:id/execute

# Get agent run
GET /api/v1/agents/:id/runs/:run_id

Tenants​

Manage multi-tenant organizations.

# List tenants
GET /api/v1/tenants

# Create tenant
POST /api/v1/tenants

# Get tenant
GET /api/v1/tenants/:id

# Update tenant settings
PATCH /api/v1/tenants/:id/settings

Chat​

AI-powered chat interface.

# Create chat session
POST /api/v1/chat/sessions

# Send message
POST /api/v1/chat/sessions/:id/messages

# Stream response
GET /api/v1/chat/sessions/:id/stream

Regions & Storage​

Manage regional preferences and storage configuration.

# List available regions
GET /api/v1/regions

# Get regional preferences
GET /api/v1/regions/preferences/:tenantId

# Update regional preferences
PATCH /api/v1/regions/preferences/:tenantId

# Get storage configuration
GET /api/v1/regions/storage/:tenantId

# Update storage configuration (Platform or BYOS)
PUT /api/v1/regions/storage/:tenantId

# Validate BYOS connection
POST /api/v1/regions/storage/:tenantId/validate

# Check feature access
GET /api/v1/regions/features/:tenantId/check/:featureKey

# Get routing info (debug)
GET /api/v1/routing-info

Regional Preferences Schema​

{
  primaryRegion: string;        // e.g., "us-east", "eu-west"
  secondaryRegion?: string;     // Failover region (Growth+)
  dataResidencyRequired: boolean;
  dataResidencyRegion?: string;
  complianceLevel: string;      // "standard", "gdpr", "hipaa", etc.
}

Storage Configuration Schema​

{
  storageMode: "platform" | "byos";
  platformRegion?: string;      // For platform storage
  byosProvider?: string;        // "s3", "r2", "gcs", "azure"
  byosEndpoint?: string;
  byosBucket?: string;
  byosRegion?: string;
  byosAccessKey?: string;       // Encrypted at rest
  byosSecretKey?: string;       // Encrypted at rest
}

Webhooks​

Subscribe to events in your DgiDgi One account:

# Register webhook
POST /api/v1/webhooks
{
  "url": "https://your-app.com/webhooks",
  "events": ["project.created", "agent.completed"],
  "secret": "your_webhook_secret"
}

Webhook Events​

  • project.created - New project created
  • project.updated - Project updated
  • project.deleted - Project deleted
  • agent.started - Agent execution started
  • agent.completed - Agent execution completed
  • agent.failed - Agent execution failed
  • tenant.created - New tenant created
  • user.created - New user registered

SDKs​

Always Use SDK

Never make direct API calls. Always use the official SDK for:

  • Automatic authentication handling
  • Type safety
  • Token refresh
  • Consistent error handling
  • React Query integration (for React apps)

Official SDKs are available for:

  • JavaScript/TypeScript: pnpm add @dgidgi/sdk (Documentation)
  • Python: Coming soon
  • Go: Coming soon

Examples​

Initialize SDK​

import { createClient, projects, agents, chat } from '@dgidgi/sdk';

// Initialize once at app startup
createClient({
  baseURL: process.env.DGIDGI_API_URL || '/api/v1',
});

Create a Project​

import { projects } from '@dgidgi/sdk';

const project = await projects.create({
  name: 'My AI App',
  description: 'An AI-powered application',
  language: 'TypeScript',
});

console.log(project.id);

Using React Hooks​

import { useProjects, useChat } from '@dgidgi/sdk';

function MyComponent() {
  // Query with automatic caching
  const { projects } = useProjects();

  // Mutations with cache invalidation
  const { actions: { create } } = useProjects();

  await create.mutateAsync({
    name: 'New Project',
  });
}

Execute an AI Agent​

import { agents } from '@dgidgi/sdk';

const agent = await agents.create({
  name: 'Code Generator',
  systemPrompt: 'You are a helpful coding assistant',
  config: { autonomyLevel: 'medium' },
});

const run = await agents.execute(agent.id, {
  goal: 'Create a React login component',
  projectId: project.id,
});

console.log(run.output);

Stream Chat Response​

import { useStreamingChat } from '@dgidgi/sdk';

function ChatComponent() {
  const {
    currentText,
    isStreaming,
    streamMessage,
    cancelStream
  } = useStreamingChat();

  const handleSend = async (message: string) => {
    await streamMessage({
      sessionId: 'session-123',
      content: message,
      projectId: 'project-456',
    });
  };

  return (
    <div>
      <div>{currentText}</div>
      {isStreaming && <button onClick={cancelStream}>Stop</button>}
    </div>
  );
}

CLI Usage​

#!/usr/bin/env node
import { createClient, projects } from '@dgidgi/sdk';

// Initialize for CLI
createClient({
  baseURL: process.env.DGIDGI_API_URL,
});

// List projects
const { data } = await projects.list();
data.forEach(p => console.log(`${p.id}\t${p.name}`));

Next Steps​

Support​