Changelog

curl -H "Authorization: Bearer $TOKEN" \
  "$BACKEND/me/usage?start_date=2026-06-23&end_date=2026-07-22"

{ "usage": {
    "window":  { "start_date": "2026-06-23", "end_date": "2026-07-22" },
    "totals":  { "spend": 12.34, "total_tokens": 1540000, "api_requests": 415 },
    "daily":   [ { "date": "2026-07-21", "spend": 0.84, ... } ],
    "byModel": [ { "model": "claude-sonnet-4-5", "spend": 9.10, ... } ] } }

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$BACKEND/admin/budgets/project/42" \
  -d '{ "max_budget": 300, "budget_duration": "30d",
        "budget_reset_at": "2026-08-01T00:00:00.000Z" }'

# 200 → { "budget": { "name", "spend", "max_budget", "budget_duration",
#                     "budget_reset_at", "budget_id" } }

# Step prompt — reference the triggering email with single braces:

Classify the request in "{email_subject}" from {email_from}.
If it is a spare-part request, extract part numbers and quantities from:

{email_body}

new ExuluTool({
  id: "acme_crm",
  name: "Acme CRM",
  inputSchema: z.object({ query: z.string() }),
  authentication: {
    authType: "user_credentials",
    provider: "acme",
    fields: [{ name: "apiKey", label: "API Key", type: "password" }],
  },
  // runs only once credentials exist — decrypted and injected per user
  execute: async (inputs) => acme.search(inputs.query, inputs.credentials.apiKey),
});

curl -X POST https://<your-backend>/credentials/submit \
  -H "content-type: application/json" \
  --cookie "<authenticated session>" \
  -d '{ "nonce": "<from credentialRequest>", "values": { "apiKey": "sk-acme-…" } }'
# → { "ok": true }

# List published agents (the whitelisted public projection, nothing more)
curl "$BACKEND/public-agents"

# One agent's public meta — 404 once it's unpublished
curl "$BACKEND/public-agents/$AGENT_ID/meta"

# Verify a shared password — 204 on match, 401 otherwise (rate-limited)
curl -X POST "$BACKEND/public-agents/$AGENT_ID/verify-password" \
  -H 'Content-Type: application/json' -d '{"password":"..."}'

{
  "id": "knowledge_base_editor",
  "type": "function",
  "name": "Knowledge base editor",
  "config": [
    { "name": "knowledge_bases", "type": "json",
      // Record<contextId, { create: boolean; update: boolean }>
      "value": "{\"products\":{\"create\":true,\"update\":true},\"faq\":{\"create\":true,\"update\":false}}" },
    { "name": "skip_approval", "type": "boolean", "value": false }
  ]
}

curl -fsSL https://exulu.your-company.com/api/skills/install.sh | sh

exulu list                      # skills you can access
exulu get <name>                # one skill's metadata
exulu install <name>            # install into your agent clients
exulu update [<name>]           # update all installed skills, or one
exulu publish <name> <dir>      # publish a local skill folder
exulu config                    # show backend / scope / clients

# list skills you can access
curl -H "x-api-key: Bearer $EXULU_API_KEY" \
  "$EXULU_BACKEND/skills/registry"

# download one (latest or a pinned version)
curl -H "x-api-key: Bearer $EXULU_API_KEY" \
  "$EXULU_BACKEND/skills/registry/grill-me/download?version=latest"

# publish a new version (zip body)
curl -X POST -H "x-api-key: Bearer $EXULU_API_KEY" \
  --data-binary @grill-me.zip \
  "$EXULU_BACKEND/skills/registry/grill-me"

mutation CreateWorkflowTemplate(
  $name: String!
  $rights_mode: String!
  $agent: String!
  $steps_json: JSON!
) {
  workflow_templatesCreateOne(
    input: { name: $name, rights_mode: $rights_mode, agent: $agent, steps_json: $steps_json }
  ) {
    item { id name variables }
  }
}

mutation UpsertWorkflowSchedule($workflow: ID!, $schedule: String!) {
  upsertWorkflowSchedule(workflow: $workflow, schedule: $schedule) {
    status
  }
}

query GetWorkflowSchedule($workflow: ID!) {
  workflowSchedule(workflow: $workflow) {
    schedule
    next
  }
}

query GetJobResultById($id: ID!) {
  job_resultById(id: $id) {
    id
    state
    error
    result
    metadata
    createdAt
  }
}

mutation RunWorkflow($id: ID!, $variables: JSON!) {
  runWorkflow(id: $id, variables: $variables) { result job metadata }
}

POST /skills/{skillId}/sign
{ "filePath": "SKILL.md", "contentType": "text/markdown" }

# → { "key": "skills/{skillId}/v2/SKILL.md",
#     "url": "<presigned PUT URL>", "method": "PUT" }

PUT <presigned PUT URL>
Content-Type: text/markdown

<new SKILL.md content>

POST /skills/:skillId/version
{ "label": "Tightened safety prompt" }
# → { "newVersion": 4, "fileCount": 12 }

GET /skills/:skillId/diff?fromVersion=3&toVersion=4
# → { "fromVersion": 3, "toVersion": 4,
#     "files": [ { "path": "reference.md",
#                  "status": "modified", "diff": "..." } ] }

# Export any skill version as a portable .zip:
curl -H "Authorization: Bearer $JWT" \
  "$EXULU_BACKEND/skills/$SKILL_ID/download?version=3" \
  --output data-analysis-v3.zip
# → folder structure preserved + version.txt
#   (Skill / Skill id / Version / Files / Exported at)

mutation UpdateProject($id: ID!, $input: projectInput!) {
  projectsUpdateOneById(id: $id, input: $input) {
    item {
      id
      name
      project_items
    }
  }
}

mutation CreateProject($input: projectInput!) {
  projectsCreateOne(input: $input) {
    item {
      id
      name
      rights_mode
    }
  }
}

[
  { "name": "project_search", "variable": "true", "type": "boolean" },
  { "name": "max_steps",      "variable": "3",    "type": "number"  }
]

mutation UpdateAgentEditor($id: ID!, $max_tool_steps: Float) {
  agentsUpdateOneById(
    input: { max_tool_steps: $max_tool_steps }
    id: $id
  ) {
    item {
      id
      name
      max_tool_steps
    }
  }
}

# Any authenticated client can synthesize speech:
curl -X POST "$EXULU_BACKEND/speech" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"text":"Here is the summary you asked for."}' \
  --output reply.mp3

{
  "success": true,
  "path": "sessions/3f2a.../quarterly-report.md",
  "url": "https://s3.eu-central-1.amazonaws.com/…/user_42/sessions/3f2a…/quarterly-report.md?X-Amz-Signature=…",
  "key": "uploads/user_42/sessions/3f2a.../quarterly-report.md"
}

[READFILE OUTPUT TRUNCATED: output was 412830 characters; showing first
121600 and last 6400 characters (limit: 128000 = 25% of 128000-token
context). 284830 characters omitted. To read specific sections use:
  grep -n "pattern" <file>        # find specific text
  sed -n '1,50p' <file>           # lines 1–50
  head -n 100 <file>              # first 100 lines
  tail -n 100 <file>              # last 100 lines
  awk 'NR>=10 && NR<=50' <file>   # lines 10–50]

import { ExuluReadApi } from "@exulu/backend";

// RBAC-safe chunk read for a known file — access control applied in SQL.
const chunks = await ExuluReadApi.authorizedRead(context, user, roleId, {
  externalIds: ["handbook.pdf"],
  chunkIndexRange: { from: 0, to: 20 },
});

// Embed with the context's own embedder, resolved per caller.
const vector = await ExuluReadApi.embedQuery(context, "notice period");

// Probe the entity layer before wiring entity tools.
const hasEntities = await ExuluReadApi.entitiesAvailable(context);

new ExuluTool({
  id: "jira_create_issue",
  // ...
  oauth: {
    provider: "jira", // ← share one consent across every jira_* tool
    authorizationUrl: "https://auth.atlassian.com/authorize",
    tokenUrl: "https://auth.atlassian.com/oauth/token",
    clientId: process.env.JIRA_CLIENT_ID!,
    clientSecret: process.env.JIRA_CLIENT_SECRET!,
    scopes: JIRA_SCOPES, // must match across the provider — enforced at boot
  },
});

query GetLiteLLMCatalog {
  litellmCatalog {
    model_name
    active
    type
    max_input_tokens
    max_output_tokens
    supports_vision
    supports_function_calling
    input_cost_per_million_tokens
    output_cost_per_million_tokens
  }
}

{
  "contents": [ "..." ],
  "labels": {
    "provider_id": "default_vertex_gemini_2_5_flash_provider",
    "provider_name": "gemini-2-5-flash",
    "user_id": "42",
    "role_id": "f3a91c",
    "project_id": "7d20b4",
    "agent_id": "9c51e8"
  }
}

mutation CreateUser(
  $type: String, $apikey: String,
  $scope_mode: String, $agent_ids: JSON
) {
  usersCreateOne(input: {
    type: $type, apikey: $apikey,
    scope_mode: $scope_mode,  # "admin" | "agents"
    agent_ids: $agent_ids     # whitelist when scope_mode = "agents"
  }) {
    item { id }
  }
}

query GetFeedback($page: Int!, $limit: Int!, $filters: [FilterFeedback]) {
  feedbackPagination(page: $page, limit: $limit, filters: $filters) {
    pageInfo { itemCount pageCount }
    items { id score description agent user createdAt }
  }
}
# filters: [{ score: { eq: 0 } }]   ← the Negative tab

query GetAgentSessionMessages(
  $page: Int!
  $limit: Int!
  $filters: [FilterAgent_message]
) {
  agent_messagesPagination(page: $page, limit: $limit, filters: $filters) {
    items {
      id
      session
      content
      createdAt
    }
  }
}

mutation DeleteFeedback($id: ID!) {
  feedbackRemoveOneById(id: $id) {
    id
  }
}

curl -X POST "$BACKEND/agents/litellm/compact/$AGENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Session: $SESSION_ID" -H "User: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{"steer": "keep the exact figures from the service reports"}'
# → { "checkpoint": { …UIMessage with metadata.compaction… },
#     "occupancyEstimate": 8400, "originalTokens": 78031, "summaryTokens": 2210 }

HTTP/1.1 413

{
  "code": "CONTEXT_COMPACTION_REQUIRED",
  "message": "This conversation no longer fits the model's context window (~99,862 of 102,400 usable tokens). Compact the conversation to continue.",
  "occupancy": 99862,
  "usableWindow": 102400,
  "contextWindow": 128000
}

{
  "truncated": true,
  "notice": "Tool output truncated: ~84,213 tokens (limit 20,000). The FULL output is saved as session file \"tool-output-web_search-a1b2c3d4.txt\" — call read_session_file with { filename: \"tool-output-web_search-a1b2c3d4.txt\", offset, limit } to read specific line ranges.",
  "sessionFile": "tool-output-web_search-a1b2c3d4.txt",
  "preview": "…first ~4,000 characters kept inline…"
}

HTTP/1.1 400

{
  "error": {
    "message": "This request is ~131,072 tokens, which exceeds the model's usable context window (102,400 tokens). Reduce the conversation history.",
    "type": "invalid_request_error",
    "code": "context_length_exceeded"
  }
}

query GetChunkByIdreports($id: ID!) {
  reports_itemsChunkById(id: $id) {
    chunk_content
    chunk_index
    chunk_metadata   # pdf + page drive the PDF-at-page preview
    item_id
    item_name
    item_external_id
  }
}

query GetTeamsByIds {
  teamsPagination(page: 1, limit: 200) {
    items {
      id
      name
    }
  }
}

query GetUsersByIds($ids: [ID!]!) {
  userByIds(ids: $ids) {
    id
    name
    firstname
    lastname
    email
  }
}

mutation RunEval($id: ID!, $test_case_ids: [ID!]) {
  runEval(id: $id, test_case_ids: $test_case_ids) {
    jobs
    count
  }
}

mutation CreateEvalRun($data: eval_runInput!) {
  eval_runsCreateOne(input: $data) {
    item {
      id
      name
      agent_id
      eval_functions
      scoring_method
      pass_threshold
    }
  }
}

mutation CreateTestCase($data: test_caseInput!) {
  test_casesCreateOne(input: $data) {
    item {
      id
      name
      inputs
      expected_output
    }
  }
}

mutation RunEval($id: ID!, $test_case_ids: [ID!]) {
  runEval(id: $id, test_case_ids: $test_case_ids) {
    jobs
    count
  }
}

mutation UpdateUserRole($id: ID!, $budget_management: String) {
  rolesUpdateOneById(
    id: $id
    input: { budget_management: $budget_management }
  ) {
    item {
      id
      name
      budget_management
    }
  }
}

curl -X POST $EXULU_BACKEND/graphql \
  -H "Authorization: Bearer $EXULU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ agentsPagination(page: 1, limit: 10) { items { id name } } }"}'

{
  "model": "claude-opus-4-8",
  "availableModels": ["claude-opus-4-8", "claude-sonnet-4-6", …],
  "env": {
    "ANTHROPIC_BASE_URL": "https://<your-backend>/litellm/<project-id>",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": 1
  },
  "apiKeyHelper": "echo <your-token>"
}

"routing": { "rules": [ { "label": "Technical questions",
    "description": "Products, error codes, installation…",
    "main": ["product_manuals"], "fallback": ["support_tickets"] } ] },
"vocabulary": {
  "glossary":    [ { "term": "FST", "meaning": "Field bus controller" } ],
  "identifiers": [ { "name": "Standards", "examples": ["DIN 8100"],
                     "strategy": "exact", "contexts": ["regulations"] } ] },
"tuning": { "topK": 5, "fallbackThreshold": 0.95, "pinBoost": 0.15 }

curl -X POST https://api.exulu.app/shared-artifacts \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "s3key":     "uploads/q4-report.html",
    "name":      "q4-report",
    "auth_mode": "public",
    "expires_at": "2026-08-01T00:00:00Z"
  }'
# → { "name": "q4-report" }
# Shareable at: /artifacts/q4-report

mutation MeetingBotStart($input: MeetingBotStartInput!) {
  meetingBotStart(input: $input) { ...TranscriptionJobFields }
}

PUT  /admin/budgets/:entityType/:entityId   # upsert one budget
PUT  /admin/budgets/:entityType/bulk        # apply to many entityIds[]
GET  /me/budget                             # caller's own spend (in-chat)

# entityType ∈ user | role | team | project | agent

new ExuluContext({
  id: "contracts",
  entities: {                       // declaring this turns the layer on
    types: [
      { name: "Person",  description: "Individuals named in the contract" },
      { name: "Company", description: "Legal entities / organizations" },
    ],
    model: "<models.id uuid>", boostWeight: 0.3, canonicalLanguage: "english",
  },
});

- model_name: rerank-v4.0-pro
  litellm_params:
    model: cohere/rerank-v4.0-pro
    api_key: os.environ/COHERE_API_KEY
  model_info:
    type: reranker        # ← makes it a selectable reranker
    top_n: 20

new ExuluTool({
  id: "hubspot_crm",
  name: "HubSpot CRM",
  type: "function",
  oauth: {
    authorizationUrl: "https://app.hubspot.com/oauth/authorize",
    tokenUrl: "https://api.hubapi.com/oauth/v1/token",
    clientId: process.env.HUBSPOT_CLIENT_ID,
    clientSecret: process.env.HUBSPOT_CLIENT_SECRET,
    scopes: ["crm.objects.contacts.read"],
  },
  execute: async (inputs) => {
    const token = inputs.oauth.accessToken; // always valid here
  },
});

# On the GPU host
npx @exulu/backend exulu-start-whisper

# On the main app
TRANSCRIPTION_SERVER=http://gpu-host:9876

EXULU_USE_LITELLM=true
LITELLM_MASTER_KEY=sk-…
LITELLM_CONFIG_PATH=ee/python/.litellm/config.yaml  # default

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

model_list:
  - model_name: vertex-flash
    litellm_params:
      model: vertex_ai/gemini-2.5-flash
      vertex_project: os.environ/GOOGLE_VERTEX_PROJECT
  - model_name: claude-haiku
    litellm_params:
      model: anthropic/claude-haiku-4-5
      api_key: os.environ/ANTHROPIC_API_KEY

curl -H "Authorization: Bearer $TOKEN" \
     https://api.exulu.com/users/42/data-export \
     -o user-42-export.zip

curl -X DELETE \
     -H "Authorization: Bearer $TOKEN" \
     https://api.exulu.com/users/42

# POST a recording, get text back
curl -X POST "$EXULU_BACKEND/transcribe" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@recording.webm" \
  -F "language=en"

# → { "text": "What's the status of the Q4 launch?" }