API Reference Overview

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

Base URL

https://api.dgidgi.one

Authentication

All API requests require authentication using an API Key.

API Keys (Recommended)

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

curl https://api.dgidgi.one/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

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`RESOURCE_NOT_FOUND`	404	Resource does not exist
`VALIDATION_ERROR`	400	Invalid request parameters
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server 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-one/sdk (Documentation)
Python: Coming soon
Go: Coming soon

Examples

Initialize SDK

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

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

Create a Project

import { projects } from '@dgidgi-one/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-one/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-one/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-one/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-one/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

SDK Documentation - Complete SDK reference and usage guide
Platform Capabilities - 200+ tool operations
Security & Compliance - Authentication and security details

Support

API Status: https://status.dgidgi.one
Contact Sales: https://dgidgi.one/contact
Support Email: support@dgidgi.one

Base URL​

Authentication​

API Keys (Recommended)​

JWT Tokens​

Rate Limiting​

Response Format​

Success Response​

Error Response​

Error Codes​

Core Resources​

Projects​

AI Agents​

Tenants​

Chat​

Regions & Storage​

Regional Preferences Schema​

Storage Configuration Schema​

Webhooks​

Webhook Events​

SDKs​

Examples​

Initialize SDK​

Create a Project​

Using React Hooks​

Execute an AI Agent​

Stream Chat Response​

CLI Usage​

Next Steps​

Support​