API Reference

REST endpoints for managing projects, sources, and ingestion. Complete API reference with authentication, requests, and response examples.

Authentication

All REST calls require an API key or JWT bearer token:

Authorization: Bearer YOUR_API_KEY

Requests must be sent over HTTPS and include Content-Type: application/json when a body is provided.

See the Authentication guide for details on managing API keys and securing requests.

Base URL

https://api.ask0.ai/v1

Replace the host if you are running on a different environment.

Trigger Source Ingestion

Initiate a re-processing job for a specific source. The API is idempotent—triggering ingestion multiple times queues just one active job per source.

Learn more about configuring sources in the documentation.

POST /trigger/ingestion

Request body

{
  "sourceId": "src_123"
}

Response

201 Created when an ingestion run is successfully queued.
404 Not Found if the provided source does not exist.
409 Conflict if an ingestion run is already in progress.

{
  "runId": "ing_456",
  "sourceId": "src_123",
  "status": "queued",
  "queuedAt": "2024-05-21T15:00:00Z"
}

Project Endpoints

Projects represent top-level containers for sources, agents, and configuration. Standard CRUD operations follow JSON semantics.

See Projects Management for more information on organizing your Ask0 projects.

List Projects

GET /projects

Optional query parameters: limit, page, and search.

{
  "data": [
    {
      "id": "proj_abc",
      "name": "Docs Portal",
      "status": "active",
      "createdAt": "2024-02-10T09:30:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "hasMore": false }
}

Create Project

POST /projects

{
  "name": "Support KB",
  "description": "Sources synced from Zendesk"
}

201 Created with the new project record in the response body.

Retrieve Project

GET /projects/{projectId}

Returns the full project document including metadata and enabled features.

Update Project

PATCH /projects/{projectId}

Send a partial payload:

{
  "name": "Support Knowledge Base",
  "status": "archived"
}

Delete Project

DELETE /projects/{projectId}

204 No Content on success.
Deleting a project cascades to its sources; ensure downstream automations are disabled first.

Source Endpoints

Sources store the raw material that feeds ingestion jobs. Each source belongs to a single project.

List Sources

GET /sources?projectId=proj_abc

Query parameters: projectId (required), status, and pagination controls.

Create Source

POST /sources

{
  "projectId": "proj_abc",
  "type": "web",
  "name": "Marketing Site",
  "config": {
    "urls": ["https://example.com/docs"],
    "crawlDepth": 2
  }
}

201 Created with the full source payload.

Retrieve Source

GET /sources/{sourceId}

Returns configuration, latest ingestion status, and statistics.

Update Source

PATCH /sources/{sourceId}

Send only the fields that should change; for example:

{
  "name": "Docs Portal",
  "config": {
    "urls": ["https://example.com/api"]
  }
}

Delete Source

DELETE /sources/{sourceId}

204 No Content when the source is removed.
Associated embeddings and cached runs are scheduled for cleanup asynchronously.

Error Handling

All endpoints return standard HTTP status codes with a JSON error payload:

{
  "error": {
    "code": "source_not_found",
    "message": "No source exists with id src_missing"
  }
}

Contact support if you encounter persistent 5xx errors or need higher ingestion throughput.

GraphQL API Examples

<?php
$url = 'https://your-domain.com/graphql';

$headers = [
    'Content-Type: application/json',
    'Authorization: Bearer your-api-key'
];

$query = '
query GetBlogPosts {
    blogPosts(limit: 5) {
        nodes {
            id
            title
            publishedAt
        }
    }
}
';

$data = json_encode(['query' => $query]);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
print_r($result['data']['blogPosts']['nodes']);
?>

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type GraphQLRequest struct {
    Query string `json:"query"`
}

func main() {
    url := "https://your-domain.com/graphql"

    query := `
    query GetBlogPosts {
        blogPosts(limit: 5) {
            nodes {
                id
                title
                publishedAt
            }
        }
    }
    `

    reqBody := GraphQLRequest{Query: query}
    jsonData, _ := json.Marshal(reqBody)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer your-api-key")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    fmt.Println(result["data"])
}

File Upload API

Handle file uploads for images, documents, and other media.

Upload Single File

POST /api/upload

Form Data:

file: The file to upload
alt: Alternative text (for images)
folder: Folder path (optional)

Example:

curl -X POST "https://your-domain.com/api/upload" \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@image.jpg" \
  -F "alt=Sample image" \
  -F "folder=blog/images"

Response:

{
  "data": {
    "id": "file_123",
    "filename": "image.jpg",
    "originalName": "my-image.jpg",
    "mimeType": "image/jpeg",
    "size": 2048576,
    "url": "https://your-domain.com/uploads/image.jpg",
    "alt": "Sample image",
    "folder": "blog/images",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Upload Multiple Files

POST /api/upload/multiple

Example:

curl -X POST "https://your-domain.com/api/upload/multiple" \
  -H "Authorization: Bearer your-api-key" \
  -F "files[]=@image1.jpg" \
  -F "files[]=@image2.jpg"

Webhooks

Set up webhooks to receive real-time notifications when content changes.

For detailed webhook configuration and event handling, see the Webhooks documentation.

Configuration

scalar.config.ts

export default defineConfig({
  webhooks: {
    enabled: true,
    endpoints: [
      {
        url: 'https://your-app.com/webhook',
        events: ['create', 'update', 'delete'],
        models: ['blogPost', 'page'],
        secret: 'webhook-secret',
      },
    ],
  },
});

Webhook Payload

{
  "event": "create",
  "model": "blogPost",
  "data": {
    "id": "1",
    "title": "New Blog Post",
    "status": "published",
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "timestamp": "2024-01-15T10:00:00Z",
  "signature": "sha256=..."
}

Verifying Webhooks

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

Rate Limiting

API requests are rate-limited to prevent abuse:

Default: 100 requests per 15 minutes per IP
Authenticated: 1000 requests per 15 minutes per API key

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Next Steps

Authentication Guide - Secure your API requests
Webhooks Documentation - Real-time event notifications
Projects Management - Organize your Ask0 projects
Sources Configuration - Add knowledge sources
Integration Guides - Add Ask0 to your platform

API Reference

On this page