Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bytestack.com/llms.txt

Use this file to discover all available pages before exploring further.

The ByteStack REST API gives you programmatic access to every capability on the platform — submitting natural language queries, scheduling recurring jobs, retrieving stored results, and registering webhooks. All requests are authenticated with a Bearer token and target the base URL https://api.bytestack.dev/v1.

​
Authentication

Include your API key as a Bearer token on every request. 
Authorization: Bearer YOUR_API_KEY
You can find and rotate your API keys in the dashboard under Settings → API Keys.

​
Queries

Use the Queries resource to submit a natural language prompt against one or more sources and retrieve results.

​
Submit a query

​
prompt
string
required
The natural language question or instruction to execute against the selected sources.
​
sources
string[]
required
List of source identifiers to query. Examples: "x", "reddit", "linkedin", "youtube", "tiktok", "instagram", "facebook".
​
date_range
object
Optional time window to restrict results.
​
limit
number
default:"100"
Maximum number of results to return. Accepts 1–1000.
curl --request POST \
  --url https://api.bytestack.dev/v1/queries \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "prompt": "How many times was Acme mentioned on X this week?",
    "sources": ["x", "reddit"],
    "date_range": {
      "start": "2026-04-24T00:00:00Z",
      "end": "2026-04-30T23:59:59Z"
    },
    "limit": 250
  }'
Response
​
id
string
required
Unique identifier for this query. Use it to poll for results.
​
status
string
required
Current status: queued, running, completed, or failed.
​
created_at
string
required
ISO 8601 timestamp of when the query was submitted.
{
  "id": "qry_01hx9jk2p4n5m6r7s8t9u0v1w",
  "status": "queued",
  "created_at": "2026-04-30T14:02:00Z"
}

​
Get query results

Retrieve the status and results of a previously submitted query.
​
id
string
required
The query ID returned from POST /v1/queries.
curl --request GET \
  --url https://api.bytestack.dev/v1/queries/qry_01hx9jk2p4n5m6r7s8t9u0v1w \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response
​
id
string
required
Query identifier.
​
status
string
required
queued, running, completed, or failed.
​
result
object
Present when status is completed.
​
error
string
Error message when status is failed.
{
  "id": "qry_01hx9jk2p4n5m6r7s8t9u0v1w",
  "status": "completed",
  "created_at": "2026-04-30T14:02:00Z",
  "completed_at": "2026-04-30T14:02:38Z",
  "result": {
    "summary": "Acme was mentioned 1,284 times across X and Reddit this week, with 62% positive sentiment.",
    "total_results": 1284,
    "result_url": "https://api.bytestack.dev/v1/storage/qry_01hx9jk2p4n5m6r7s8t9u0v1w/result.json",
    "records": []
  }
}

​
Jobs

Jobs let you schedule a query to run automatically on a cron schedule. Each run stores results and can notify your endpoint via webhook.

​
List jobs

curl --request GET \
  --url https://api.bytestack.dev/v1/jobs \
  --header 'Authorization: Bearer YOUR_API_KEY'

{
  "jobs": [
    {
      "id": "job_01hx9jk2p4n5m6r7s8t9u0v1w",
      "name": "Daily Acme mentions",
      "status": "active",
      "schedule": "0 8 * * *",
      "last_run_at": "2026-04-30T08:00:00Z",
      "next_run_at": "2026-05-01T08:00:00Z"
    }
  ]
}

​
Create a job

​
name
string
required
A human-readable label for the job.
​
prompt
string
required
The natural language query to execute on each run.
​
sources
string[]
required
List of source identifiers to query.
​
schedule
string
required
Cron expression defining the run frequency, e.g. "0 8 * * *" for 08:00 UTC daily.
​
webhook_url
string
Optional URL to receive a POST callback when each run completes.
curl --request POST \
  --url https://api.bytestack.dev/v1/jobs \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Daily Acme mentions",
    "prompt": "How many times was Acme mentioned on X today?",
    "sources": ["x"],
    "schedule": "0 8 * * *",
    "webhook_url": "https://yourapp.example.com/webhooks/bytestack"
  }'

{
  "id": "job_01hx9jk2p4n5m6r7s8t9u0v1w",
  "name": "Daily Acme mentions",
  "status": "active",
  "schedule": "0 8 * * *",
  "created_at": "2026-04-30T14:05:00Z",
  "next_run_at": "2026-05-01T08:00:00Z"
}

​
Update a job

Pause or resume a job, change its schedule, or update its webhook URL.
​
id
string
required
The job ID to update.
​
status
string
Set to "paused" or "active" to pause or resume the job.
​
schedule
string
New cron expression for the job.
​
webhook_url
string
Updated webhook URL.
curl --request PATCH \
  --url https://api.bytestack.dev/v1/jobs/job_01hx9jk2p4n5m6r7s8t9u0v1w \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "paused"
  }'

{
  "id": "job_01hx9jk2p4n5m6r7s8t9u0v1w",
  "status": "paused",
  "updated_at": "2026-04-30T15:00:00Z"
}

​
Delete a job

​
id
string
required
The job ID to delete. This action is irreversible.
curl --request DELETE \
  --url https://api.bytestack.dev/v1/jobs/job_01hx9jk2p4n5m6r7s8t9u0v1w \
  --header 'Authorization: Bearer YOUR_API_KEY'

{
  "deleted": true,
  "id": "job_01hx9jk2p4n5m6r7s8t9u0v1w"
}

​
Storage

ByteStack stores every job run result as a file you can list and download through the API or the dashboard Storage tab.

​
List result files

curl --request GET \
  --url https://api.bytestack.dev/v1/storage \
  --header 'Authorization: Bearer YOUR_API_KEY'

{
  "files": [
    {
      "key": "job_01hx9jk2p4n5m6r7s8t9u0v1w/2026-04-30T08:00:00Z.json",
      "size_bytes": 48320,
      "created_at": "2026-04-30T08:01:22Z"
    }
  ]
}

​
Download a result file

​
key
string
required
The file key returned from GET /v1/storage. URL-encode slashes or pass as a path segment.
curl --request GET \
  --url 'https://api.bytestack.dev/v1/storage/job_01hx9jk2p4n5m6r7s8t9u0v1w%2F2026-04-30T08%3A00%3A00Z.json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --output result.json
The response body is the raw JSON result file.

​
Webhooks

Register an endpoint to receive POST callbacks when job runs complete.

​
Register a webhook

​
url
string
required
The HTTPS endpoint ByteStack should POST results to.
​
events
string[]
List of event types to subscribe to. Defaults to ["job.completed"].
curl --request POST \
  --url https://api.bytestack.dev/v1/webhooks \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://yourapp.example.com/webhooks/bytestack",
    "events": ["job.completed"]
  }'

{
  "id": "wh_01hx9jk2p4n5m6r7s8t9u0v1w",
  "url": "https://yourapp.example.com/webhooks/bytestack",
  "events": ["job.completed"],
  "created_at": "2026-04-30T14:10:00Z"
}

​
Delete a webhook

​
id
string
required
The webhook ID to delete.
curl --request DELETE \
  --url https://api.bytestack.dev/v1/webhooks/wh_01hx9jk2p4n5m6r7s8t9u0v1w \
  --header 'Authorization: Bearer YOUR_API_KEY'

{
  "deleted": true,
  "id": "wh_01hx9jk2p4n5m6r7s8t9u0v1w"
}

​
Error codes

ByteStack uses standard HTTP status codes. All error responses include a JSON body with a code and message field. 
{
  "error": {
    "code": "rate_limited",
    "message": "You have exceeded your request quota. Retry after 60 seconds."
  }
}
StatusMeaning
400 Bad RequestThe request body is missing required fields or contains invalid values.
401 UnauthorizedThe Authorization header is missing or the API key is invalid.
402 Payment RequiredYour account has a billing issue. Check Settings → Billing in the dashboard.
403 ForbiddenYour API key does not have permission to perform this action.
404 Not FoundThe requested resource does not exist.
429 Too Many RequestsYou have exceeded your rate limit. Respect the Retry-After header.
500 Internal Server ErrorAn unexpected error occurred on ByteStack’s servers. Contact support if it persists.