> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read the authorized workforce projection

> Human-only bounded read contract. Organization owners/admins may request the full inventory or a project filter. Other human members must have effective admin access to the requested project and receive only explicitly scoped agents plus personal agents whose owner inherits access. Unauthorised project filters are concealed as 404. The response omits credentials, emails, auth IDs, hidden projects, private content, lifecycle fields, and organization capacity; project-admin read visibility does not grant management authority.



## OpenAPI

````yaml /openapi.json get /api/orgs/{id}/agents/workforce
openapi: 3.1.0
info:
  title: Atoll API
  version: 1.0.0
  description: >-
    REST API for Atoll project management, agent collaboration, strategy
    tracking, and integrations.
servers:
  - url: https://atollhq.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Authentication
  - name: Organizations
  - name: Projects
  - name: Project access
  - name: Issues
  - name: Issue details
  - name: Milestones
  - name: Artifacts
  - name: Strategy
  - name: Members and agents
  - name: Planning
  - name: Setup
  - name: Integrations and billing
  - name: Notifications and public
  - name: Private inbox
  - name: Agent executions
  - name: Human attention
paths:
  /api/orgs/{id}/agents/workforce:
    get:
      tags:
        - Members and agents
      summary: Read the authorized workforce projection
      description: >-
        Human-only bounded read contract. Organization owners/admins may request
        the full inventory or a project filter. Other human members must have
        effective admin access to the requested project and receive only
        explicitly scoped agents plus personal agents whose owner inherits
        access. Unauthorised project filters are concealed as 404. The response
        omits credentials, emails, auth IDs, hidden projects, private content,
        lifecycle fields, and organization capacity; project-admin read
        visibility does not grant management authority.
      operationId: get_api_orgs_id_agents_workforce
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Organization identifier
        - name: projectId
          in: query
          required: false
          schema:
            type: string
          description: Project filter; required for project-admin reads
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Authorized workforce projection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkforceAgentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - humanSessionAuth: []
components:
  schemas:
    WorkforceAgentsResponse:
      type: object
      additionalProperties: false
      required:
        - agents
        - total
        - limit
        - offset
        - nextOffset
        - truncated
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/WorkforceAgent'
        total:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
          maximum: 100
        offset:
          type: integer
          minimum: 0
        nextOffset:
          type:
            - integer
            - 'null'
          minimum: 0
        truncated:
          type: boolean
    WorkforceAgent:
      type: object
      additionalProperties: false
      required:
        - id
        - display_name
        - avatar_url
        - role
        - created_at
        - last_used_at
        - scope
        - project_ids
        - projects
        - owner
        - capabilities
      properties:
        id:
          type: string
          format: uuid
        display_name:
          type:
            - string
            - 'null'
        avatar_url:
          type:
            - string
            - 'null'
        role:
          type: string
        created_at:
          type: string
          format: date-time
        last_used_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Latest authenticated use from an active API key or non-revoked OAuth
            profile.
        scope:
          type: string
          enum:
            - personal
            - project
            - organization
        project_ids:
          type: array
          items:
            type: string
            format: uuid
        projects:
          type: array
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
            additionalProperties: false
        owner:
          oneOf:
            - type: object
              additionalProperties: false
              required:
                - display_name
                - avatar_url
              properties:
                display_name:
                  type:
                    - string
                    - 'null'
                avatar_url:
                  type:
                    - string
                    - 'null'
            - type: 'null'
        capabilities:
          $ref: '#/components/schemas/WorkforceAgentCapabilities'
        key_prefix:
          type:
            - string
            - 'null'
          description: >-
            Optional non-secret API-key prefix, present only when the caller
            already has key-management authority.
    Error:
      type: object
      description: >-
        Common error responses contain error. Shared missing-auth and
        unknown-API responses also contain a stable code.
      properties:
        error:
          type: string
        code:
          type: string
      required:
        - error
      examples:
        - error: Unauthorized
          code: unauthorized
        - error: Not found
          code: not_found
      additionalProperties: true
    WorkforceAgentCapabilities:
      type: object
      additionalProperties: false
      required:
        - can_view
        - can_manage_access
        - can_manage_keys
        - can_disable
        - can_revoke
      properties:
        can_view:
          type: boolean
        can_manage_access:
          type: boolean
        can_manage_keys:
          type: boolean
        can_disable:
          type: boolean
        can_revoke:
          type: boolean
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Authenticated but not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found or not visible
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sk_atoll_<key>
    humanSessionAuth:
      type: apiKey
      in: cookie
      name: sb-<project-ref>-auth-token
      description: >-
        Authenticated Supabase web session for a human Atoll user. The cookie
        name includes the deployment's Supabase project reference and may be
        chunked.

````