Documentation

Artexion provides deterministic, bounded, observable execution for AI tasks.

What Artexion Is

Artexion is a runtime API for executing AI tasks with explicit state transitions, hard runtime bounds, and durable execution records.

Use Artexion when you need:

  • durable, stateful tasks
  • a structured execution plan generated before execution
  • hard limits on steps, tokens, and time
  • sequential step execution with no speculative parallelism
  • explicit failure states and persisted execution traces
  • Docker-based sandbox execution for code steps (network disabled by default)
  • API-key runtime auth and OAuth dashboard access

Execution Model

Execution is deterministic for the same task input, plan, tool set, and limits.

Execution flow:

  1. Request is accepted and stored as a durable task record.
  2. A structured plan is generated (or validated if explicitly provided).
  3. Hard bounds are applied before execution starts.
  4. Task enters queue and executes steps sequentially.
  5. Each step writes durable trace records before and after execution.
  6. First unrecoverable step error halts execution and task enters failed.
  7. On full completion, task enters succeeded with deterministic hashes.

Operational guarantees:

  • no hidden retries inside a task execution
  • no speculative parallel step execution
  • failure halts further step execution
  • every step and state transition is persisted

Task Lifecycle

Artexion enforces a forward-only task state machine:

created → planned → queued → running → succeeded | failed

State definitions:

  • created: Task record persisted.
  • planned: Execution plan persisted and validated.
  • queued: Task accepted for worker execution.
  • running: Worker started executing plan steps.
  • succeeded: Task completed all steps successfully (terminal).
  • failed: Task stopped due to validation, execution, timeout, or system error (terminal).

Rules:

  • tasks cannot regress to previous states
  • terminal states (succeeded, failed) are immutable
  • status transitions are validated by the state machine and DB-level guards

Authentication

Artexion uses:

  • OAuth for dashboard and account access
  • API keys for runtime API access

Send your API key in the Authorization header:

Authorization: Bearer atx_live_your_key

Recommended local setup:

export ARTEXION_API_KEY="atx_live_your_key"

Security baseline:

  • keep keys in a secrets manager
  • never commit keys to source control
  • rotate and revoke unused keys

Execute a Task

Submit a task for planning + execution:

curl -X POST https://api.artexion.com/api/v1/tasks/execute \
  -H "Authorization: Bearer $ARTEXION_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "task_definition": {
      "topic": "Summarize weekly release notes"
    },
    "max_steps": 12,
    "timeout_seconds": 45
  }'

Request JSON:

{
  "task_definition": {
    "topic": "Summarize weekly release notes"
  },
  "max_steps": 12,
  "timeout_seconds": 45
}

Response JSON:

{
  "version": "prod-2026-02-27",
  "task_id": "185d012b-a332-4924-b84c-8edd78d64975",
  "status": "queued",
  "duration_seconds": 0.0,
  "cost_usd": 0.0,
  "result": {
    "queued": true
  },
  "error": null,
  "failure": null
}

Inspect Task State

Fetch current task state and persisted plan/result:

curl -H "Authorization: Bearer $ARTEXION_API_KEY" \
  https://api.artexion.com/api/v1/tasks/<task_id>

Response JSON:

{
  "version": "prod-2026-02-27",
  "id": "185d012b-a332-4924-b84c-8edd78d64975",
  "task_id": "185d012b-a332-4924-b84c-8edd78d64975",
  "replay_of_task_id": null,
  "input": {
    "topic": "Summarize weekly release notes"
  },
  "status": "running",
  "plan": {
    "steps": [
      {
        "step_index": 1,
        "tool": "math",
        "input": {
          "expression": "1+1"
        }
      }
    ],
    "limits": {
      "max_steps": 12,
      "max_total_seconds": 45,
      "max_step_seconds": 10
    }
  },
  "result": null,
  "error": null,
  "created_at": "2026-02-27T11:18:01.127894+00:00",
  "execution_started_at": "2026-02-27T11:18:02.991451+00:00",
  "execution_finished_at": null,
  "failure": null
}

Inspect Execution Trace

Fetch the full execution trace (events, steps, and summary):

curl -H "Authorization: Bearer $ARTEXION_API_KEY" \
  https://api.artexion.com/api/v1/tasks/<task_id>/trace

Response JSON:

{
  "version": "prod-2026-02-27",
  "task_id": "185d012b-a332-4924-b84c-8edd78d64975",
  "replay_of_task_id": null,
  "status": "failed",
  "failure": {
    "step": "python_sandbox",
    "index": 2,
    "code": "TIMEOUT",
    "message": "STEP_TIMEOUT: Step execution timed out"
  },
  "estimated_cost_usd": 0.0012,
  "events": [
    {
      "event": "task.status_transition",
      "payload": {
        "from": "queued",
        "to": "running",
        "at": "2026-02-27T11:18:02.991451+00:00"
      },
      "created_at": "2026-02-27T11:18:02.991471+00:00"
    }
  ],
  "steps": [
    {
      "id": "fe5e1e18-e2cc-4985-845f-76c0e24c7a65",
      "step_index": 1,
      "tool_name": "math",
      "input": {
        "expression": "1+1"
      },
      "output": {
        "result": 2
      },
      "status": "succeeded",
      "error": null,
      "started_at": "2026-02-27T11:18:03.101100+00:00",
      "finished_at": "2026-02-27T11:18:03.112844+00:00",
      "duration_ms": 11
    }
  ],
  "plan_validation_failures": [],
  "runtime_schema_failures": [],
  "summary": {
    "total_steps": 2,
    "succeeded_steps": 1,
    "failed_steps": 1,
    "running_steps": 0,
    "total_duration_ms": 5011,
    "sandbox_runs": 1,
    "task_hash": "b2f17a0f4934d40c3af10051f84fce6e39567d14d31f12f0b098b0af8cad3f1c",
    "step_hashes": [
      "dcd43eb43a0e8c6f899fd2cf4c886f009447eb8fdb5da7cbc35d5ab2ec32f0a8"
    ],
    "queue_latency_ms": 147,
    "retry_count": 0
  }
}

Logs and Usage

Use task trace events and usage APIs for operational visibility:

  • logs/events: status transitions, failures, schema mismatches
  • trace: per-step inputs, outputs, timing, and errors
  • usage: request counts, timeout limits, and active-task count

Useful links:

  • API dashboard: https://api.artexion.com/dashboard
  • Usage endpoint: https://api.artexion.com/api/v1/tasks/usage

Usage example:

curl -H "Authorization: Bearer $ARTEXION_API_KEY" \
  https://api.artexion.com/api/v1/tasks/usage

Response JSON:

{
  "user_id": 42,
  "email": "eng@example.com",
  "plan": "pro",
  "monthly_requests": 1643,
  "monthly_task_executions": 1588,
  "total_usage_usd": 23.48,
  "rate_limit_per_minute": 120,
  "max_timeout_seconds": 60,
  "max_tasks_per_request": 1,
  "active_tasks": 2
}

Limits and Operational Guidance

Artexion enforces hard bounds on steps, tokens, and time before execution starts, and rejects requests that exceed policy.

Operational recommendations:

  • start with test keys for integration
  • move to live keys only after validation
  • set explicit max_steps and timeout_seconds per task
  • treat failed as terminal and create a new task for replay/rerun
  • alert on non-zero retry_count, failed_steps, and timeout codes
  • monitor usage and active task count against plan limits

Links:

Need Help? Documentation: https://artexion.com/docs.html — Contact: contact@artexion.com