AI Response
POST/api/ai/
Send a prompt as JSON and authenticate with your API key in the Authorization: Bearer header (or X-API-Key). Omit agent and model to use your package defaults and automatic fallback. Select cloudflare with a Workers AI model ID to run the prompt only through the configured Cloudflare accounts and models. If a model is unavailable or quota-limited, the service tries another eligible Cloudflare text model and records the active model for this domain. Cloudflare requests currently accept text prompts without uploaded attachments or downloadable file generation. Models marked Advanced Model share a separate monthly call allowance; each advanced attempt counts toward it. The response identifies the agent and model used.
Basic Request
curl -X POST 'https://www.ai.darmist.com/api/ai/' -H 'Authorization: Bearer API_KEY' -H 'Content-Type: application/json' -d '{"prompt":"Hello, what can you do?"}'
Request With a Selected Agent and Model
curl -X POST 'https://www.ai.darmist.com/api/ai/' -H 'Authorization: Bearer API_KEY' -H 'Content-Type: application/json' -d '{"prompt":"Explain this code","agent":"antigravity","model":"model-id"}'
Request With Cloudflare Workers AI
curl -X POST 'https://www.ai.darmist.com/api/ai/' -H 'Authorization: Bearer API_KEY' -H 'Content-Type: application/json' -d '{"prompt":"Explain this code","agent":"cloudflare","model":"@cf/meta/llama-3.1-8b-instruct"}'
Request With Attachments
First upload each file with POST /api/files/, then pass the returned file IDs. Package limits may be lower than five attachments.
{
"prompt": "Summarize this document",
"file_ids": ["FILE_ID"]
}
Use the same API key that uploaded the files. Attachments count toward estimated input tokens. Supported file formats depend on the selected agent.
Success Response
{
"response": "...",
"agent": "codex",
"model": "gpt-6-luna",
"input_tokens": 1234,
"files": [{ "id": "FILE_ID", "name": "report.pdf", "size": 12345, "mime_type": "application/pdf", "expires_at": "2026-10-31T00:00:00+00:00", "download_url": "api/files/download/?id=FILE_ID" }]
}
input_tokens is the server's estimate based on prompt and attachment bytes, not the CLI's measured model usage.
Ask the agent to generate a file. Finished files are returned in files and expire after 24 hours. Package limits may be lower than the system maximum of five files, 10 MiB each. File creation depends on the selected agent.
Error Responses
Errors return a JSON object with an error message. The message varies by cause. Examples:
400 Bad Request
{ "error": "Enter a prompt before sending." }
401 Unauthorized
{ "error": "A valid API key is required. Send it in the Authorization: Bearer header." }
403 Forbidden
{ "error": "This agent is not included in your assigned package." }
404 Not Found
{ "error": "An attachment is unavailable or expired." }
405 Method Not Allowed
{ "error": "Only POST requests are supported." }
413 Content Too Large
{ "error": "An attachment exceeds this package’s file size limit." }
415 Unsupported Media Type
{ "error": "Content-Type must be application/json." }
429 Too Many Requests
{ "error": "This subscription has reached its monthly request limit." }
429 Too Many Requests
{ "error": "This subscription has reached its monthly advanced model call limit." }
500 Internal Server Error
{ "error": "No enabled AI CLI is currently available for this package." }
502 Bad Gateway
{ "error": "No enabled agent could complete the request." }
503 Service Unavailable
{ "error": "Package usage could not be verified. Please try again." }
Upload Attachment
POST/api/files/
Upload one file using multipart/form-data with the field name file. Authenticate with Authorization: Bearer or X-API-Key. Files must be between 1 byte and 10 MiB. Supported extensions are txt, csv, json, pdf, png, jpg and jpeg; the detected content type must match the extension.
Upload Example
curl -X POST 'https://www.ai.darmist.com/api/files/' -H 'Authorization: Bearer API_KEY' -F 'file=@/path/to/document.pdf'
Success Response (HTTP 201)
{
"id": "FILE_ID",
"name": "document.pdf",
"mime_type": "application/pdf",
"size": 12345,
"created_at": "2026-10-30T00:00:00+00:00",
"expires_at": "2026-10-31T00:00:00+00:00"
}
Use the returned ID in an AI request. Attachments expire after 24 hours and can only be used by their owner. Expired uploads are not automatically deleted.
Error Responses
Errors return a JSON object with an error message. Examples:
400 Bad Request
{ "error": "Provide one file in the file field." }
401 Unauthorized
{ "error": "A valid API key is required." }
403 Forbidden
{ "error": "File uploads are not included in this package." }
405 Method Not Allowed
{ "error": "Only POST requests are supported." }
413 Content Too Large
{ "error": "The file exceeds this package’s upload size limit." }
415 Unsupported Media Type
{ "error": "Unsupported file type or mismatched file content." }
429 Too Many Requests
{ "error": "This package has reached its monthly upload limit." }
500 Internal Server Error
{ "error": "The file could not be stored." }
503 Service Unavailable
{ "error": "Upload storage is unavailable." }
Download Generated File
GET/api/files/download/?id={file_id}
Download a generated file using the API key of its owner in Authorization: Bearer or X-API-Key. Files expire after 24 hours. Expired files are not automatically deleted.
Download Example
curl -L 'https://www.ai.darmist.com/api/files/download/?id=FILE_ID' -H 'Authorization: Bearer API_KEY' -o report.pdf
Success Response
HTTP 200 OK
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="download"; filename*=UTF-8''report.pdf
Binary file contents are streamed as the response body.
Error Responses
Errors return a JSON object with an error message. Examples:
401 Unauthorized
{ "error": "A valid API key is required." }
404 Not Found
{ "error": "File unavailable or expired." }
405 Method Not Allowed
{ "error": "Only GET requests are supported." }
429 Too Many Requests
{ "error": "Too many invalid API key attempts." }
Models
GET/api/models/
Authenticate with Authorization: Bearer API_KEY or X-API-Key to list the enabled agents and configured model IDs for the API key's package. When Cloudflare accounts are configured, the response also includes their Workers Free eligible models. Add ?agent=cloudflare to filter to Cloudflare. AI requests still use the package's request, token, and advanced model limits.
Request Example
curl 'https://www.ai.darmist.com/api/models/?agent=cloudflare' -H 'Authorization: Bearer API_KEY'
Success Response
{
"package_id": "spark",
"default_agent": "codex",
"agents": [{ "id": "cloudflare", "default_model": "@cf/meta/llama-3.1-8b-instruct", "models": ["@cf/meta/llama-3.1-8b-instruct"] }]
}
Error Responses
Errors return a JSON object with an error message. Examples:
400 Bad Request
{ "error": "Invalid agent." }
401 Unauthorized
{ "error": "A valid API key is required." }
403 Forbidden
{ "error": "This agent is not included in your assigned package." }
405 Method Not Allowed
{ "error": "Only GET requests are supported." }
429 Too Many Requests
{ "error": "Too many invalid API key attempts." }
Package Usage
GET/api/package-usage/
Requires an API key in the X-API-Key header or Authorization: Bearer. Returns usage counters for each active subscription belonging to the key’s user, including request, advanced model call, token, and rate-limit totals and limits. Advanced model calls count attempts to models marked Advanced Model. Counters cover the subscription’s current billing period. No prompt or response history is stored.
Request Example
curl 'https://www.ai.darmist.com/api/package-usage/' -H 'Authorization: Bearer API_KEY'
Success Response
{
"usages": [{
"subscription_id": "...",
"package_id": "...",
"package_name": "...",
"is_default": true,
"period_start": "...",
"period_end": "...",
"subscription_end": "...",
"requests": 12,
"monthly_request_limit": 1000,
"monthly_requests_remaining": 988,
"advanced_model_calls": 3,
"monthly_advanced_model_call_limit": 20,
"monthly_advanced_model_calls_remaining": 17,
"input_tokens": 2400,
"input_token_limit": 8192,
"output_tokens": 900,
"output_token_limit": 4096,
"uploaded_files": 2,
"monthly_upload_limit": 25,
"generated_files": 1,
"monthly_generated_limit": 10,
"requests_last_minute": 1,
"requests_per_minute_limit": 10,
"requests_last_hour": 8,
"requests_per_hour_limit": 60
}]
}
Error Responses
Errors return a JSON object with an error message. Examples:
401 Unauthorized
{ "error": "A valid API key is required." }
405 Method Not Allowed
{ "error": "Only GET requests are supported." }
429 Too Many Requests
{ "error": "Too many invalid API key attempts. Try again shortly." }
503 Service Unavailable
{ "error": "Package usage could not be verified. Please try again." }