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
}

Integrating Artexion into Automation Workflows

Artexion integrates cleanly into automation workflows that require deterministic execution, hard runtime bounds, and durable traces. Each task produces a persistent execution record and follows a forward-only state machine: created → planned → queued → running → succeeded | failed.

Generic Integration Pattern

Most automation platforms expose an HTTP request node or module. Use the same pattern across n8n, Zapier, and Make:

  1. Trigger the workflow (webhook, schedule, CRM event).
  2. POST a task to Artexion.
  3. Read task_id from the response.
  4. Poll task status until terminal (succeeded or failed).
  5. Use the result or failure metadata downstream.

Workflow Diagram

Trigger
  → POST /api/v1/tasks/execute
  → task_id
  → Poll GET /api/v1/tasks/{task_id}
  → succeeded | failed
  → result handling

HTTP Request Configuration

  • Method: POST
  • URL: https://api.artexion.com/api/v1/tasks/execute
  • Headers: Authorization: Bearer <ARTEXION_API_KEY>, Content-Type: application/json

JSON body:

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

curl example:

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
  }'

n8n

  1. Add a Trigger node (Webhook, Cron, or app connector).
  2. Add an HTTP Request node:
    • Method: POST
    • URL: https://api.artexion.com/api/v1/tasks/execute
    • Headers: Authorization: Bearer {{$env.ARTEXION_API_KEY}}, Content-Type: application/json
    • Body: JSON payload as shown above.
  3. Extract task_id from the response.
  4. Add a Wait node (1–3 seconds), then an HTTP Request node:
    • Method: GET
    • URL: https://api.artexion.com/api/v1/tasks/{{$json["task_id"]}}
  5. Branch on status and loop until terminal.

Zapier

  1. Use a Zap trigger (schedule, webhook, or app event).
  2. Webhooks by Zapier → Custom Request:
    • Method: POST
    • URL: https://api.artexion.com/api/v1/tasks/execute
    • Headers: Authorization: Bearer <ARTEXION_API_KEY>, Content-Type: application/json
    • Data: JSON payload as shown above.
  3. Store task_id from the response.
  4. Add Delay or Looping by Zapier, then a GET request to the task status endpoint.

Make (Integromat)

  1. Add a trigger module (Scheduler or app module).
  2. HTTP → Make a request:
    • Method: POST
    • URL: https://api.artexion.com/api/v1/tasks/execute
    • Headers: Authorization: Bearer <ARTEXION_API_KEY>, Content-Type: application/json
    • Body type: Raw → JSON payload as shown above.
  3. Parse the response and capture task_id.
  4. Tools → Sleep (1–3 seconds), then HTTP → Make a request:
    • Method: GET
    • URL: https://api.artexion.com/api/v1/tasks/{task_id}
  5. Route based on status and repeat until terminal.

Poll Task Status

Use the task status endpoint and stop polling once the task reaches a terminal state.

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

Terminal states are succeeded and failed. Non-terminal states should continue to be polled with a backoff.

Best Practices

  • Set explicit max_steps and timeout_seconds for each task.
  • Use exponential backoff for polling to avoid rate limits.
  • Treat failed as terminal; create a new task for retries.
  • Log task_id in your automation runs for traceability.
  • Handle timeouts and rate-limit responses at the automation layer.

When to Use Artexion in Automation

Use Artexion when an automation step requires deterministic execution, strict runtime bounds, and an auditable execution trace. For simple transformations or synchronous checks that do not require durable state, a direct HTTP step without task execution may be sufficient.

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 a live key 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: