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

# Get the Agency workspace

> Workspace identity, the caller's role, remaining shared project quota, and one page of the workspace's client reports - dashboard-created ones included, newest first, without report bodies. Consultant and AppSumo Agency accounts only: a key whose account holds no Agency workspace, or whose membership was removed, gets 404 AGENCY_NOT_FOUND on the next call. Membership is resolved live on every request, independently of the key.




## OpenAPI

````yaml /api-reference/openapi.yaml get /api/agent/agency
openapi: 3.1.0
info:
  title: Preuve Agent API
  version: '2.0'
  description: >
    API for programmatic startup idea validation. Every request carries a single
    x-preuve-key header holding the whole API key - no signing, no bearer token.
    See the Authentication guide.
servers:
  - url: https://preuve.ai
security:
  - preuveKey: []
paths:
  /api/agent/agency:
    get:
      tags:
        - Agency
      summary: Get the Agency workspace
      description: >
        Workspace identity, the caller's role, remaining shared project quota,
        and one page of the workspace's client reports - dashboard-created ones
        included, newest first, without report bodies. Consultant and AppSumo
        Agency accounts only: a key whose account holds no Agency workspace, or
        whose membership was removed, gets 404 AGENCY_NOT_FOUND on the next
        call. Membership is resolved live on every request, independently of the
        key.
      operationId: getAgency
      parameters:
        - name: limit
          in: query
          required: false
          description: Client reports to return in the reports array.
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - name: offset
          in: query
          required: false
          description: Paging offset into the reports array.
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
      responses:
        '200':
          description: Workspace, role, quota, and one page of client reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgencyContext'
        '400':
          description: limit must be 1-50 and offset 0-10000 (INVALID_PAGINATION).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: >
            Key does not carry agency:read (INSUFFICIENT_SCOPE) or the account
            is suspended (ACCOUNT_SUSPENDED). agency:write does not imply it.
            Keys created before 2026-09-09 predate both Agency scopes and always
            fail this check - see the AgencyInsufficientScope response for the
            recovery and the condition on each of its two routes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          $ref: '#/components/responses/AgencyNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    AgencyContext:
      type: object
      properties:
        agency:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            role:
              type: string
              description: The calling account's role in the workspace.
        quota:
          $ref: '#/components/schemas/AgencyQuota'
        canRunScan:
          type: boolean
          description: >
            Eligibility, not live availability. True only when the role may run
            scans, the workspace is approved, billing setup is done, and quota
            remains. It does not read the service kill switch, the LLM pause or
            the rate limiters, so a start can still answer 503 or 429 while this
            is true. None of those refusals spends a project credit.
        reports:
          type: array
          description: >
            One page of the workspace's client reports, newest first, including
            ones created in the Agency dashboard. Same shape and paging as
            /api/agent/agency/reports.
          items:
            $ref: '#/components/schemas/AgencyReportListItem'
        nextOffset:
          type: integer
          nullable: true
          description: |
            Offset of the next page of reports, or null on the last page.
    ApiError:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable message.
        code:
          type: string
          description: Stable machine-readable code. Branch on this.
        details:
          description: Optional context (validation errors, limits, ...).
    AgencyQuota:
      type: object
      description: Shared project quota for the workspace, same pool as the dashboard.
      properties:
        plan:
          type: string
        isActiveSubscription:
          type: boolean
        trialLimit:
          type: integer
        trialUsed:
          type: integer
        trialExpired:
          type: boolean
        delinquent:
          type: boolean
        monthlyLimit:
          type: integer
        monthlyUsed:
          type: integer
        monthlyRemaining:
          type: integer
        topupRemaining:
          type: integer
        totalRemaining:
          type: integer
        requiresPaymentSetup:
          type: boolean
        canScan:
          type: boolean
        nextResetAt:
          type: string
          format: date-time
          nullable: true
    AgencyReportListItem:
      type: object
      description: One client report in the workspace, without its payload.
      properties:
        reportId:
          type: string
        title:
          type: string
          nullable: true
        status:
          type: string
        scanType:
          type: string
          enum:
            - starter
            - deep
        createdAt:
          type: string
          format: date-time
        reportUrl:
          type: string
          format: uri
  responses:
    AgencyNotFound:
      description: >
        No Agency workspace on this account, or workspace membership was removed
        (AGENCY_NOT_FOUND). Membership is resolved live on every call.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: Rate limited (RATE_LIMITED or DAILY_LIMIT_REACHED).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    preuveKey:
      type: apiKey
      in: header
      name: x-preuve-key
      description: >
        Your API key (prv_...), sent as-is. It is the only credential the API
        needs - see the Authentication guide.

````