Tasks & Artifacts

Tasks and Artifacts are the two core primitives in Ariftly. Every piece of work an agent does is a Task. Every structured output an agent produces is an Artifact.

Tasks

A Task is an async unit of work dispatched to an agent. Tasks are the primary way to instruct an agent to do something — and they are the unit by which agent work is tracked, audited, and billed.

Every task has:

task_id — unique identifier (e.g., task_xyz789)
task_type — what the agent should do (e.g., ai_readiness.full_audit)
input — validated against the agent's manifest schema for that task type
status — current execution state
artifacts — typed outputs produced when the task completes
created_at / completed_at — timestamps for duration tracking
tenant_id — the organization that owns the task

Task Lifecycle

pending → running → complete
                 ↘ failed
                 ↘ cancelled

pending — the task has been created and queued. The agent has not started processing it yet.

running — the agent is actively executing the task. For long-running audits, you may see progress events emitted while the task is in this state.

complete — the task finished successfully. Artifacts are now available.

failed — the task encountered an unrecoverable error. The error field on the task record contains the reason. Common causes: integration credentials revoked, agent timeout, malformed input.

cancelled — the task was manually cancelled via the API or dashboard before it completed. Partial artifacts, if any, are discarded.

Tasks are dispatched asynchronously. For automated workflows, register a webhook instead of polling.

Triggering a Task

Tasks can be started from multiple trigger sources:

Dashboard — click Run Task on any agent card
API — POST /v1/tasks with a task_type and input payload
Schedule — cron-based recurring tasks (e.g., weekly AI readiness pulse checks)
Event — triggered automatically when another agent emits a specific artifact type
Channel — triggered by an inbound Gmail forwarding rule or a Slack message matching a configured pattern

Creating a task via API

curl -X POST https://api.ariftly.io/v1/tasks \
  -H "Authorization: Bearer $ARIFTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ai-readiness-agent",
    "task_type": "ai_readiness.full_audit",
    "input": {
      "scope": "full",
      "focus_framework": "eu_ai_act"
    }
  }'

Response:

{
  "task_id": "task_xyz789",
  "status": "pending",
  "created_at": "2026-04-23T10:00:00Z"
}

Polling task status

curl https://api.ariftly.io/v1/tasks/task_xyz789 \
  -H "Authorization: Bearer $ARIFTLY_API_KEY"

Cancelling a task

curl -X POST https://api.ariftly.io/v1/tasks/task_xyz789/cancel \
  -H "Authorization: Bearer $ARIFTLY_API_KEY"

Only tasks in pending or running state can be cancelled. Completed tasks cannot be cancelled, but their artifacts can be deleted.

Webhooks for task completion

Instead of polling, register a webhook to receive a POST request when a task completes:

curl -X POST https://api.ariftly.io/v1/webhooks \
  -H "Authorization: Bearer $ARIFTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.com/hooks/ariftly",
    "events": ["task.complete", "task.failed"],
    "secret": "your_webhook_secret"
  }'

The webhook payload includes the full task record, including all artifact IDs. Verify the request using the X-Ariftly-Signature header — see Authentication for HMAC verification details.

Artifacts

An Artifact is a typed, structured output produced by a task. Artifacts are immutable once created — they represent a point-in-time output of the agent's work. Run a new task to produce a fresh artifact.

Common Artifact Types

Agent	Artifact Type	Description
AI Readiness	`ai_readiness.audit_report`	Full EU AI Act / NIST compliance gap report with scores and remediation priorities
AI Readiness	`ai_readiness.questionnaire_response`	Draft answers to procurement questionnaires, grounded in your codebase evidence
AI Readiness	`ai_readiness.gap_summary`	Lightweight gap list for executive sharing, without technical detail
Sales	`sales.lead_list`	Discovered leads matching your ICP, with company metadata
Sales	`sales.enriched_lead_list`	Leads enriched with verified email contacts, tech stack, and intent signals
Sales	`sales.email_draft`	Personalized outreach email ready for your approval
Sales	`sales.pipeline_report`	Reply tracking, open rates, and conversion summary for an outreach sequence

Fetching an artifact

curl https://api.ariftly.io/v1/artifacts/art_001 \
  -H "Authorization: Bearer $ARIFTLY_API_KEY"

Response:

{
  "artifact_id": "art_001",
  "task_id": "task_xyz789",
  "type": "ai_readiness.audit_report",
  "created_at": "2026-04-23T10:04:22Z",
  "data": {
    "gaps_found": 14,
    "critical": 3,
    "eu_ai_act_score": 62,
    "domains": {
      "risk_classification": 45,
      "human_oversight": 70,
      "data_governance": 55,
      "transparency": 80,
      "security": 65,
      "technical_documentation": 40
    },
    "recommendations": [
      {
        "gap": "No model card for production LLM pipeline",
        "severity": "critical",
        "evidence_missing": ["docs/models/", "model_card.json"],
        "remediation": "Create a model card at docs/models/llm-pipeline.md documenting training data, intended use, and risk classification"
      }
    ]
  }
}

Listing artifacts for a task

curl "https://api.ariftly.io/v1/artifacts?task_id=task_xyz789" \
  -H "Authorization: Bearer $ARIFTLY_API_KEY"

Artifact retention

Artifacts are retained for 90 days on the Free and Starter plans, and indefinitely on Pro and Enterprise plans. Artifacts that require human approval (e.g., sales.email_draft) are retained for 7 days if not acted on, then auto-expire. You can configure this retention window in Settings → Data Retention.

Artifacts requiring approval

Some artifact types are gated by the Approvals system before they take effect. For example, a sales.email_draft artifact exists as a draft in Ariftly — it does not leave your Gmail account until you explicitly approve it. The artifact record includes an approval_status field:

{
  "artifact_id": "art_002",
  "type": "sales.email_draft",
  "approval_status": "pending",
  "data": {
    "to": "alex.kim@acme.com",
    "subject": "AI Readiness tooling for ACME",
    "body": "..."
  }
}

What's next

Approvals & Skills — how approval-gated artifacts work
Tasks API Reference — full endpoint documentation
RAP v1 Protocol — how agents emit artifacts and events back to Core

Tasks​

Task Lifecycle​

Triggering a Task​

Creating a task via API​

Polling task status​

Cancelling a task​

Webhooks for task completion​

Artifacts​

Common Artifact Types​

Fetching an artifact​

Listing artifacts for a task​

Artifact retention​

Artifacts requiring approval​

What's next​