GraphQL API Documentation

Overview

ARC-OS provides a comprehensive GraphQL API for all operations. The API is tenant-aware, RBAC-protected, and supports real-time subscriptions.

Endpoint

POST /api/graphql

Authentication

All requests must include a JWT token in the Authorization header:

Authorization: Bearer <token>

Schema

The GraphQL schema includes:

• Identity: Users, roles, entitlements, API keys
• Plans: Plans, plan cycles, participants, payroll, contributions
• Workflows: Projects, tasks, worktrays, assignments
• Compliance: Testing, corrections, rule versions
• Filings: Form 5500, Form 8955-SSA, notices
• Documents: Document artifacts, specifications, templates
• Communications: Interactions, blast campaigns, email templates
• Portal: Data collection, secure exchange, bulletins
• Distributions: Distribution cases, approvals
• Audit: Audit ledger, evidence bundles
• Agents: Agent tasks, decisions, tool invocations
• Controls: Controls, control runs, findings

Queries

Plans

query {
  plans {
    id
    name
    planType
    ein
    client {
      id
      name
    }
    cycles {
      id
      periodStart
      periodEnd
      status
    }
  }
  
  plan(id: "plan-id") {
    id
    name
    planType
  }
  
  planCycle(id: "cycle-id") {
    id
    periodStart
    periodEnd
    status
  }
}

Worktrays

query {
  worktrays {
    id
    name
    assignments {
      id
      task {
        id
        name
        status
      }
    }
  }
}

Documents

query {
  documents {
    id
    name
    status
    fileUrl
    createdAt
  }
}

Interactions

query {
  interactions(entityId: "plan-id", type: "email") {
    id
    type
    subject
    content
    createdAt
  }
}

Compliance

query {
  testResults(planCycleId: "cycle-id") {
    id
    testType
    result
    riskScore
  }
  
  correctionCases(planId: "plan-id") {
    id
    errorType
    status
    correctionPath
  }
}

Audit

query {
  auditLedger(limit: 100) {
    id
    action
    actorId
    resourceType
    createdAt
  }
  
  evidenceBundles {
    id
    bundleType
    isSealed
    sealedAt
  }
}

Mutations

Plan Operations

mutation {
  openPlanCycle(planId: "plan-id", periodStart: "2024-01-01", periodEnd: "2024-12-31") {
    id
    status
  }
}

Work Operations

mutation {
  assignWorkItem(taskId: "task-id", worktrayId: "worktray-id") {
    id
    assignedTo
  }
}

Approvals

mutation {
  approveHumanApproval(approvalId: "approval-id", decision: "approved", reason: "Looks good") {
    id
    status
    approvedAt
  }
}

Communications

mutation {
  sendEmail(
    recipient: "user@example.com"
    subject: "Test Email"
    body: "Email content"
    planId: "plan-id"
  ) {
    id
    type
  }
}

Subscriptions

Workflow Updates

subscription {
  workflowUpdates(correlationId: "correlation-id") {
    eventType
    payload
    timestamp
  }
}

Inbox Updates

subscription {
  inboxUpdates(userId: "user-id") {
    id
    status
    decisionId
  }
}

Plan Cycle Updates

subscription {
  planCycleUpdates(planCycleId: "cycle-id") {
    id
    status
    updatedAt
  }
}

Authorization

All queries, mutations, and subscriptions enforce:

1. Tenant Isolation: Users can only access data from their tenant
2. RBAC Permissions: Actions require appropriate permissions
3. Entitlement Tiers: Features may require TRACK/TEAM/BUSINESS tier
4. Field Redaction: PSL/external audiences see redacted data
5. Autonomy Policy: Agent actions respect autonomy levels

Error Handling

GraphQL errors follow the standard format:

{
  "errors": [
    {
      "message": "Permission denied: read on plan",
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ]
}

Rate Limiting

• Standard users: 1000 requests/hour
• API keys: Based on tier (1000-10000 requests/hour)

Versioning

The API version is included in the schema. Current version: 1.0.0