Clarity Solutions API

openapi: 3.2.0
info:
  title: Fast Solutions API
  version: 0.1.0
tags:
- name: Solutions
paths:
  /api/v1/solutions:
    get:
      tags:
      - Solutions
      summary: List Solutions
      description: 'Every project''s solutions, newest change first, with the totals the scoreboard shows.


        Args:

        solution_status: Only solutions in this status.

        project_id: Only this project''s solutions.

        hidden: Only hidden (true) or only visible (false) solutions.


        Returns:

        The solutions, plus their total fetches and adoptions.'
      operationId: list_solutions_api_v1_solutions_get
      security:
      - HTTPBearer: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SolutionStatus'
          - type: 'null'
          title: Status
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 9223372036854775807
            exclusiveMinimum: 0
          - type: 'null'
          description: Only this project's
          title: Project Id
        description: Only this project's
      - name: hidden
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: 'true: only hidden · false: only visible'
          title: Hidden
        description: 'true: only hidden · false: only visible'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolutionListResponse'
        '401':
          description: Not authenticated
        '403':
          description: Not a staff admin
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/solutions/apps:
    get:
      tags:
      - Solutions
      summary: List Apps
      description: 'Every live mini-app with its description, eligibility, verdict and the solutions it is in.


        Args:

        project_id: Only this project''s apps.

        eligible: Only eligible (true) or only not-eligible (false) apps.

        verdict: Only apps judged this way.


        Returns:

        The apps, newest change first.'
      operationId: list_apps_api_v1_solutions_apps_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 9223372036854775807
            exclusiveMinimum: 0
          - type: 'null'
          description: Only this project's
          title: Project Id
        description: Only this project's
      - name: eligible
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          description: 'true: eligible when last described · false: not, or never described'
          title: Eligible
        description: 'true: eligible when last described · false: not, or never described'
      - name: verdict
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/VerdictValue'
          - type: 'null'
          title: Verdict
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppListResponse'
        '401':
          description: Not authenticated
        '403':
          description: Not a staff admin
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/solutions/apps/{app_id}/rejudge:
    post:
      tags:
      - Solutions
      summary: Rejudge App
      description: 'Ask the next pipeline run to judge the app again (accepted, not done now).


        Raises:

        HTTPException: 404 when the pipeline has never described the app.'
      operationId: rejudge_app_api_v1_solutions_apps__app_id__rejudge_post
      security:
      - HTTPBearer: []
      parameters:
      - name: app_id
        in: path
        required: true
        schema:
          type: integer
          maximum: 9223372036854775807
          exclusiveMinimum: 0
          title: App Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RejudgeResponse'
        '401':
          description: Not authenticated
        '403':
          description: Not a staff admin
        '404':
          description: The app was never described
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/solutions/runs:
    get:
      tags:
      - Solutions
      summary: List Runs
      description: The latest pipeline runs (backfill and scheduled sweeps), newest first.
      operationId: list_runs_api_v1_solutions_runs_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 10
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/src__solutions_v2__schemas__RunListResponse'
        '401':
          description: Not authenticated
        '403':
          description: Not a staff admin
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/solutions/{solution_id}:
    get:
      tags:
      - Solutions
      summary: Get Solution
      description: 'One solution: its text, pieces (with where each opens), adoption and the admin lock.


        Raises:

        HTTPException: 404 when it does not exist or its project is deleted.'
      operationId: get_solution_api_v1_solutions__solution_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: solution_id
        in: path
        required: true
        schema:
          type: integer
          maximum: 9223372036854775807
          exclusiveMinimum: 0
          title: Solution Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolutionResponse'
        '401':
          description: Not authenticated
        '403':
          description: Not a staff admin
        '404':
          description: Unknown, or its project is deleted
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/solutions/{solution_id}/hide:
    post:
      tags:
      - Solutions
      summary: Hide Solution
      description: 'Hide a solution: shared nowhere, at once, and never unhidden by the pipeline.


        Raises:

        HTTPException: 404 when it does not exist.'
      operationId: hide_solution_api_v1_solutions__solution_id__hide_post
      security:
      - HTTPBearer: []
      parameters:
      - name: solution_id
        in: path
        required: true
        schema:
          type: integer
          maximum: 9223372036854775807
          exclusiveMinimum: 0
          title: Solution Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolutionResponse'
        '401':
          description: Not authenticated
        '403':
          description: Not a staff admin
        '404':
          description: Unknown, or its project is deleted
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/solutions/{solution_id}/unhide:
    post:
      tags:
      - Solutions
      summary: Unhide Solution
      description: 'Lift the admin lock: the solution is searchable again if its status allows.


        Raises:

        HTTPException: 404 when it does not exist.'
      operationId: unhide_solution_api_v1_solutions__solution_id__unhide_post
      security:
      - HTTPBearer: []
      parameters:
      - name: solution_id
        in: path
        required: true
        schema:
          type: integer
          maximum: 9223372036854775807
          exclusiveMinimum: 0
          title: Solution Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SolutionResponse'
        '401':
          description: Not authenticated
        '403':
          description: Not a staff admin
        '404':
          description: Unknown, or its project is deleted
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PieceResponse:
      properties:
        kind:
          $ref: '#/components/schemas/PieceKind'
        ref:
          type: string
          title: Ref
          description: The entity id, a flow id, a connection id, a memory-doc path, or 'project'
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        role:
          type: string
          title: Role
          description: The piece's job in the solution
        ui_path:
          anyOf:
          - type: string
          - type: 'null'
          title: Ui Path
          description: Relative UI path that opens it, while it is live
      type: object
      required:
      - kind
      - ref
      - role
      title: PieceResponse
    RejudgeResponse:
      properties:
        app_id:
          type: integer
          title: App Id
        requested:
          type: boolean
          title: Requested
          description: The next run judges the app again
      type: object
      required:
      - app_id
      - requested
      title: RejudgeResponse
    PieceKind:
      type: string
      enum:
      - mini_app
      - collection
      - routine
      - operator
      - workflow
      - connection
      - memory_doc
      - signals
      title: PieceKind
      description: 'What a piece of a solution points at. The first four are live-examples kinds too, so an

        agent can fetch them through ``detail_path``; the others are listed without one.'
    src__solutions_v2__schemas__RunListResponse:
      properties:
        runs:
          items:
            $ref: '#/components/schemas/src__solutions_v2__schemas__RunResponse'
          type: array
          title: Runs
      type: object
      required:
      - runs
      title: RunListResponse
    EligibilityResponse:
      properties:
        highlights:
          type: integer
          title: Highlights
          default: 0
        likers:
          type: integer
          title: Likers
          default: 0
        edit_days:
          type: integer
          title: Edit Days
          default: 0
        eligible:
          type: boolean
          title: Eligible
          default: false
      type: object
      title: EligibilityResponse
      description: The signals when the description was written, and whether they made the app eligible.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SolutionSummaryResponse:
      properties:
        id:
          type: integer
          title: Id
        project:
          $ref: '#/components/schemas/ProjectRefResponse'
        use_case:
          type: string
          title: Use Case
          description: The label solutions of the same use case share across projects
        title:
          type: string
          title: Title
        summary:
          type: string
          title: Summary
          description: 'Written for other projects'' agents: names no customer'
        status:
          $ref: '#/components/schemas/SolutionStatus'
          description: 'shared: every project finds it · project_only: the name check kept it to its own project · merged / retired: no longer searchable, kept for history'
        hidden:
          type: boolean
          title: Hidden
          description: 'An admin hid it: shared nowhere, and the pipeline never unhides it'
        revision:
          type: integer
          title: Revision
          description: Bumped each time a run rewrote its content
        piece_count:
          type: integer
          title: Piece Count
        piece_kinds:
          items:
            $ref: '#/components/schemas/PieceKind'
          type: array
          title: Piece Kinds
          description: The kinds of piece it is built from, in build order
        fetch_count:
          type: integer
          title: Fetch Count
          description: How many times an agent fetched it from the examples search
        adopted_count:
          type: integer
          title: Adopted Count
          description: How many solutions were built from it
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - project
      - use_case
      - title
      - summary
      - status
      - hidden
      - revision
      - piece_count
      - piece_kinds
      - fetch_count
      - adopted_count
      - updated_at
      title: SolutionSummaryResponse
      description: One solution as the list shows it.
    AppResponse:
      properties:
        app_id:
          type: integer
          title: App Id
        slug:
          type: string
          title: Slug
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        project:
          $ref: '#/components/schemas/ProjectRefResponse'
        live_version:
          type: integer
          title: Live Version
        described_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Described Version
          description: The version the description is of
        description:
          anyOf:
          - $ref: '#/components/schemas/AppDescriptionResponse'
          - type: 'null'
        eligibility:
          anyOf:
          - $ref: '#/components/schemas/EligibilityResponse'
          - type: 'null'
        verdict:
          anyOf:
          - $ref: '#/components/schemas/VerdictValue'
          - type: 'null'
          description: Only eligible apps are judged
        verdict_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Verdict Reason
        rejudge_requested_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Rejudge Requested At
        solution_ids:
          items:
            type: integer
          type: array
          title: Solution Ids
          description: The solutions it is part of (merged excluded)
        ui_path:
          type: string
          title: Ui Path
      type: object
      required:
      - app_id
      - slug
      - project
      - live_version
      - ui_path
      title: AppResponse
      description: One live mini-app with what the pipeline knows about it.
    FlaggedTermResponse:
      properties:
        where:
          type: string
          title: Where
          default: ''
        term:
          type: string
          title: Term
          default: ''
        snippet:
          type: string
          title: Snippet
          default: ''
      type: object
      title: FlaggedTermResponse
      description: What the name check found in the shared text (why a solution is project_only).
    SolutionStatus:
      type: string
      enum:
      - shared
      - project_only
      - merged
      - retired
      title: SolutionStatus
    ProjectRefResponse:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
      type: object
      required:
      - id
      - name
      title: ProjectRefResponse
    VerdictValue:
      type: string
      enum:
      - good
      - ok
      - bad
      title: VerdictValue
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SolutionLinkResponse:
      properties:
        from_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: From Kind
        from_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: From Ref
        relation:
          anyOf:
          - type: string
          - type: 'null'
          title: Relation
        to_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: To Kind
        to_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: To Ref
      type: object
      title: SolutionLinkResponse
      description: One structured connection between two pieces ("the app reads collection 12").
    SolutionBodyResponse:
      properties:
        problem:
          type: string
          title: Problem
          default: ''
        how_it_works:
          type: string
          title: How It Works
          default: ''
        build_order:
          items:
            type: string
          type: array
          title: Build Order
        links:
          items:
            $ref: '#/components/schemas/SolutionLinkResponse'
          type: array
          title: Links
      type: object
      title: SolutionBodyResponse
    SolutionListResponse:
      properties:
        solutions:
          items:
            $ref: '#/components/schemas/SolutionSummaryResponse'
          type: array
          title: Solutions
        fetches:
          type: integer
          title: Fetches
          description: Total fetches of the listed solutions
        adoptions:
          type: integer
          title: Adoptions
          description: Total solutions built from the listed ones
      type: object
      required:
      - solutions
      - fetches
      - adoptions
      title: SolutionListResponse
    src__solutions_v2__schemas__RunResponse:
      properties:
        id:
          type: integer
          title: Id
        mode:
          $ref: '#/components/schemas/src__solutions_v2__constants__RunMode'
        status:
          $ref: '#/components/schemas/src__solutions_v2__constants__RunStatus'
        started_at:
          type: string
          format: date-time
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
        stats:
          additionalProperties: true
          type: object
          title: Stats
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - id
      - mode
      - status
      - started_at
      title: RunResponse
    SolutionRefResponse:
      properties:
        id:
          type: integer
          title: Id
        title:
          type: string
          title: Title
        project_id:
          type: integer
          title: Project Id
        status:
          $ref: '#/components/schemas/SolutionStatus'
      type: object
      required:
      - id
      - title
      - project_id
      - status
      title: SolutionRefResponse
      description: Another solution named from this one (adapted from / built from it).
    src__solutions_v2__constants__RunStatus:
      type: string
      enum:
      - running
      - ok
      - error
      title: RunStatus
    SolutionResponse:
      properties:
        id:
          type: integer
          title: Id
        project:
          $ref: '#/components/schemas/ProjectRefResponse'
        use_case:
          type: string
          title: Use Case
          description: The label solutions of the same use case share across projects
        title:
          type: string
          title: Title
        summary:
          type: string
          title: Summary
          description: 'Written for other projects'' agents: names no customer'
        status:
          $ref: '#/components/schemas/SolutionStatus'
          description: 'shared: every project finds it · project_only: the name check kept it to its own project · merged / retired: no longer searchable, kept for history'
        hidden:
          type: boolean
          title: Hidden
          description: 'An admin hid it: shared nowhere, and the pipeline never unhides it'
        revision:
          type: integer
          title: Revision
          description: Bumped each time a run rewrote its content
        piece_count:
          type: integer
          title: Piece Count
        piece_kinds:
          items:
            $ref: '#/components/schemas/PieceKind'
          type: array
          title: Piece Kinds
          description: The kinds of piece it is built from, in build order
        fetch_count:
          type: integer
          title: Fetch Count
          description: How many times an agent fetched it from the examples search
        adopted_count:
          type: integer
          title: Adopted Count
          description: How many solutions were built from it
        updated_at:
          type: string
          format: date-time
          title: Updated At
        body:
          $ref: '#/components/schemas/SolutionBodyResponse'
        flagged_terms:
          items:
            $ref: '#/components/schemas/FlaggedTermResponse'
          type: array
          title: Flagged Terms
        pieces:
          items:
            $ref: '#/components/schemas/PieceResponse'
          type: array
          title: Pieces
          description: In build order
        quality:
          type: number
          title: Quality
        adapted_from:
          anyOf:
          - $ref: '#/components/schemas/SolutionRefResponse'
          - type: 'null'
        derived:
          items:
            $ref: '#/components/schemas/SolutionRefResponse'
          type: array
          title: Derived
          description: Solutions adapted from this one
        merged_into:
          anyOf:
          - type: integer
          - type: 'null'
          title: Merged Into
        hidden_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Hidden At
        hidden_by:
          anyOf:
          - type: integer
          - type: 'null'
          title: Hidden By
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - project
      - use_case
      - title
      - summary
      - status
      - hidden
      - revision
      - piece_count
      - piece_kinds
      - fetch_count
      - adopted_count
      - updated_at
      - body
      - flagged_terms
      - pieces
      - quality
      - created_at
      title: SolutionResponse
      description: One solution with everything the solution page shows.
    AppListResponse:
      properties:
        apps:
          items:
            $ref: '#/components/schemas/AppResponse'
          type: array
          title: Apps
      type: object
      required:
      - apps
      title: AppListResponse
    AppDescriptionResponse:
      properties:
        summary:
          type: string
          title: Summary
          default: ''
        job:
          type: string
          title: Job
          default: ''
        users:
          type: string
          title: Users
          default: ''
        problems:
          items:
            type: string
          type: array
          title: Problems
        use_cases:
          items:
            type: string
          type: array
          title: Use Cases
        activities:
          items:
            type: string
          type: array
          title: Activities
        replaces:
          type: string
          title: Replaces
          default: ''
      type: object
      title: AppDescriptionResponse
      description: An app in business terms, as the pipeline wrote it.
    src__solutions_v2__constants__RunMode:
      type: string
      enum:
      - backfill
      - incremental
      title: RunMode
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic