Revyl User API

openapi: 3.2.0
info:
  description: Revyl API
  title: Revyl User API
  version: 1.0.0
servers:
- description: Production
  url: https://backend.revyl.ai
tags:
- name: User
paths:
  /api/v1/entity/users/cli-device-authorizations:
    post:
      description: 'Start a browser approval for a CLI that cannot complete a local login.


        Unauthenticated by necessity: the caller has no credential yet, which is the

        point. Creating an authorization grants nothing on its own; only a signed-in

        user''s approval mints a credential, and only the caller holding the returned

        device code can redeem it.


        Parameters:

        request: Optional device label, per-install identifier, and bounded

        launcher (`client_source`) when the Cursor plugin started login.


        Returns:

        CreateCLIDeviceAuthorizationResponse: The device code, the short user

        code, both approval URLs, and the polling budget.


        Raises:

        HTTPException 429: When the per-IP creation limit is exceeded.

        HTTPException 503: When no authorization could be registered.'
      operationId: create_cli_device_authorization_endpoint_api_v1_entity_users_cli_device_authorizations_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/CreateCLIDeviceAuthorizationRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCLIDeviceAuthorizationResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Cli Device Authorization Endpoint
      tags:
      - User
  /api/v1/entity/users/cli-device-authorizations/credentials:
    post:
      description: 'Return the credential to the CLI holding the device code, exactly once.


        Unauthenticated by necessity and authorized by the device code alone, which

        is why that code is high entropy, travels only in the request body, and stops

        working the moment it is redeemed.


        Parameters:

        request: The device code issued when the authorization was created.


        Returns:

        RedeemCLIDeviceCredentialResponse: The pending state while the user has

        not decided, the denial, or the credential on the redeeming poll.


        Raises:

        HTTPException 404: If the device code is unknown, expired, or spent.

        HTTPException 429: When the per-IP poll limit is exceeded.'
      operationId: redeem_cli_device_credential_endpoint_api_v1_entity_users_cli_device_authorizations_credentials_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemCLIDeviceCredentialRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemCLIDeviceCredentialResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Redeem Cli Device Credential Endpoint
      tags:
      - User
  /api/v1/entity/users/get_dashboard_metrics:
    get:
      description: 'Get dashboard metrics with week-over-week comparisons for tests and workflows.


        Onboarding, billing, and Atlas facts come from primary and always

        reflect current state. When the eventual-read lane is unavailable this

        still returns 200 with ``analytics_degraded=True`` and placeholder

        execution aggregates, because none of the chrome the dashboard gates on

        depends on that lane.


        Returns:

        DashboardMetrics: Dashboard metrics including total tests, workflows, test runs,

        failing tests percentage, average duration, and their WoW comparisons'
      operationId: get_dashboard_metrics_endpoint_api_v1_entity_users_get_dashboard_metrics_get
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardMetrics'
          description: Successful Response
      security:
      - HTTPBearer: []
      summary: Get Dashboard Metrics Endpoint
      tags:
      - User
  /api/v1/entity/users/get_user_uuid:
    get:
      description: 'Get the user id of the current user.


        Supports both regular user authentication and service key authentication.

        For service keys, returns AuthInfo with user_id="service".'
      operationId: get_user_uuid_endpoint_api_v1_entity_users_get_user_uuid_get
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthInfo'
          description: Successful Response
      security:
      - HTTPBearer: []
      summary: Get User Uuid Endpoint
      tags:
      - User
  /api/v1/entity/users/revoke_cli_api_key:
    post:
      description: Revoke the current machine's browser-issued CLI API key.
      operationId: revoke_cli_api_key_endpoint_api_v1_entity_users_revoke_cli_api_key_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeCLIApiKeyRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeCLIApiKeyResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
      - HTTPBearer: []
      summary: Revoke Cli Api Key Endpoint
      tags:
      - User
components:
  schemas:
    CreateCLIDeviceAuthorizationResponse:
      description: Pending authorization handed back to the CLI that started it.
      properties:
        device_code:
          description: Secret the CLI presents to redeem the credential. Never displayed or logged.
          maxLength: 128
          minLength: 32
          title: Device Code
          type: string
        expires_in:
          description: Seconds until this authorization expires and must be restarted.
          title: Expires In
          type: integer
        interval:
          description: Minimum seconds the CLI should wait between credential polls.
          title: Interval
          type: integer
        user_code:
          description: Short code shown to the user so they can confirm they are approving their own login.
          pattern: ^[ABCDEFGHJKMNPQRSTVWXYZ23456789abcdefghjkmnpqrstvwxyz23456789]{4}-[ABCDEFGHJKMNPQRSTVWXYZ23456789abcdefghjkmnpqrstvwxyz23456789]{4}$
          title: User Code
          type: string
        verification_uri:
          description: Approval page to open when the complete URL cannot be used.
          title: Verification Uri
          type: string
        verification_uri_complete:
          description: Approval page with the user code embedded, so one click covers the whole flow.
          title: Verification Uri Complete
          type: string
      required:
      - device_code
      - user_code
      - verification_uri
      - verification_uri_complete
      - expires_in
      - interval
      title: CreateCLIDeviceAuthorizationResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    CLIClientSource:
      description: Bounded launcher that started a CLI device-authorization login.
      enum:
      - cursor_plugin
      title: CLIClientSource
      type: string
    RedeemCLIDeviceCredentialRequest:
      description: Poll from the CLI holding the device code.
      properties:
        device_code:
          description: Secret issued when the authorization was created.
          maxLength: 128
          minLength: 32
          title: Device Code
          type: string
      required:
      - device_code
      title: RedeemCLIDeviceCredentialRequest
      type: object
    RevokeCLIApiKeyRequest:
      description: Request to revoke a browser-issued CLI API key.
      properties:
        api_key_id:
          description: The PropelAuth-assigned API key ID to revoke.
          title: Api Key Id
          type: string
      required:
      - api_key_id
      title: RevokeCLIApiKeyRequest
      type: object
    AuthInfo:
      description: 'Class that represents authentication information.

        Can be returned from the require_auth dependency.'
      properties:
        android_concurrency_limit:
          anyOf:
          - minimum: 1.0
            type: integer
          - type: 'null'
          title: Android Concurrency Limit
        api_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
        concurrency_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Concurrency Limit
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        ios_concurrency_limit:
          anyOf:
          - minimum: 1.0
            type: integer
          - type: 'null'
          title: Ios Concurrency Limit
        org_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Org Id
        org_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Name
        permissions:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Permissions
        proxy_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Proxy Enabled
        service:
          default: false
          title: Service
          type: boolean
        user_id:
          title: User Id
          type: string
        user_role:
          anyOf:
          - type: string
          - type: 'null'
          title: User Role
      required:
      - user_id
      title: AuthInfo
      type: object
    DashboardMetrics:
      description: Model representing dashboard metrics with week-over-week comparisons.
      properties:
        analytics_degraded:
          default: false
          description: Whether the eventual-consistency analytics lane was unavailable for this response. When true, execution aggregates and week-over-week comparisons (test_runs, tests_failing_*, avg_test_duration*, success/failure_run_count, workflow_run_count, *_wow) are placeholders rather than measurements, while onboarding, billing, and Atlas facts remain current. Clients must render those analytics as unavailable instead of zero.
          title: Analytics Degraded
          type: boolean
        atlas_generation_running:
          default: false
          description: Whether an Atlas exploration run is currently queued/running. Drives the 'map is building' onboarding state and defers session-based activation while generating.
          title: Atlas Generation Running
          type: boolean
        avg_test_duration:
          anyOf:
          - type: number
          - type: 'null'
          description: Average test execution duration in seconds
          title: Avg Test Duration
        avg_test_duration_wow:
          anyOf:
          - type: number
          - type: 'null'
          description: Week-over-week percentage change in average duration (positive = increase)
          title: Avg Test Duration Wow
        checklist_app_uploaded:
          default: false
          description: Whether the user has uploaded an app (checklist step 1).
          title: Checklist App Uploaded
          type: boolean
        checklist_session_started:
          default: false
          description: Whether the user has started a device session (checklist step 2).
          title: Checklist Session Started
          type: boolean
        checklist_test_created:
          default: false
          description: Whether the user has created a test (checklist step 3).
          title: Checklist Test Created
          type: boolean
        connected_integrations:
          description: List of connected integration IDs (e.g. 'github', 'slack', 'expo'). Used for bonus session nudges.
          items:
            type: string
          title: Connected Integrations
          type: array
        dashboard_state:
          default: mature
          description: 'Dashboard view state: onboarding (checklist incomplete), intermediate (checklist done but no active plan), mature (fully active)'
          enum:
          - onboarding
          - intermediate
          - mature
          title: Dashboard State
          type: string
        failure_run_count:
          default: 0
          description: Total number of failed test execution runs.
          title: Failure Run Count
          type: integer
        has_atlas_map:
          default: false
          description: Whether the org has a renderable Atlas map (any exploration run with atlas_status completed/partial). Own-milestone fact for the atlas onboarding lens.
          title: Has Atlas Map
          type: boolean
        has_exploration:
          default: false
          description: Whether the org has started any Atlas exploration, in any state. Hides the post-setup offer to map the app.
          title: Has Exploration
          type: boolean
        org_has_apps:
          default: false
          description: Whether the org has any user-uploaded apps (controls whether 'upload app' step is shown).
          title: Org Has Apps
          type: boolean
        success_run_count:
          default: 0
          description: Total number of completed (passed) test execution runs.
          title: Success Run Count
          type: integer
        test_runs:
          description: Total number of test executions
          title: Test Runs
          type: integer
        test_runs_wow:
          anyOf:
          - type: number
          - type: 'null'
          description: Week-over-week percentage change in test runs (positive = increase)
          title: Test Runs Wow
        tests_failing_count:
          description: Raw number of tests currently failing
          title: Tests Failing Count
          type: integer
        tests_failing_count_wow:
          anyOf:
          - type: number
          - type: 'null'
          description: Week-over-week percentage change in failing tests count (positive = increase)
          title: Tests Failing Count Wow
        tests_failing_percent:
          description: Percentage of tests currently failing
          title: Tests Failing Percent
          type: number
        tests_failing_percent_wow:
          anyOf:
          - type: number
          - type: 'null'
          description: Week-over-week percentage point change in failing tests percentage (positive = increase)
          title: Tests Failing Percent Wow
        total_tests:
          description: Total number of tests
          title: Total Tests
          type: integer
        total_tests_wow:
          anyOf:
          - type: number
          - type: 'null'
          description: Week-over-week percentage change in total tests (positive = increase)
          title: Total Tests Wow
        total_workflows:
          description: Total number of workflows
          title: Total Workflows
          type: integer
        total_workflows_wow:
          anyOf:
          - type: number
          - type: 'null'
          description: Week-over-week percentage change in total workflows (positive = increase)
          title: Total Workflows Wow
        workflow_run_count:
          default: 0
          description: Total workflow executions for the org (controls workflow slot visibility)
          title: Workflow Run Count
          type: integer
      required:
      - total_tests
      - test_runs
      - tests_failing_percent
      - tests_failing_count
      - avg_test_duration
      - total_workflows
      title: DashboardMetrics
      type: object
    CreateCLIDeviceAuthorizationRequest:
      description: Request from an unauthenticated CLI to start browser approval.
      properties:
        client_instance_id:
          anyOf:
          - maxLength: 128
            pattern: ^(?:[A-Za-z0-9][A-Za-z0-9._:\-]*)?$
            type: string
          - type: 'null'
          description: Stable per-install CLI identifier used to rotate only this device's key.
          title: Client Instance Id
        client_source:
          anyOf:
          - $ref: '#/components/schemas/CLIClientSource'
          - type: 'null'
          description: Bounded launcher that started this login. Omitted for ordinary CLI.
        device_label:
          anyOf:
          - type: string
          - type: 'null'
          description: Human-readable device label shown on the approval page.
          title: Device Label
      title: CreateCLIDeviceAuthorizationRequest
      type: object
    RevokeCLIApiKeyResponse:
      description: Response from revoking a browser-issued CLI API key.
      properties:
        message:
          description: Human-readable status message.
          title: Message
          type: string
        success:
          description: Whether the CLI API key was revoked.
          title: Success
          type: boolean
      required:
      - success
      - message
      title: RevokeCLIApiKeyResponse
      type: object
    RedeemCLIDeviceCredentialResponse:
      description: 'Credential poll result.


        The credential fields are populated exactly once, on the first poll that

        observes an approval; every later poll for the same device code fails.'
      properties:
        api_key_id:
          anyOf:
          - type: string
          - type: 'null'
          description: PropelAuth-assigned key ID, present only on the redeeming poll.
          title: Api Key Id
        api_key_token:
          anyOf:
          - type: string
          - type: 'null'
          description: Minted CLI credential, present only on the redeeming poll.
          title: Api Key Token
        email:
          anyOf:
          - type: string
          - type: 'null'
          description: Email of the approving user, present only on the redeeming poll.
          title: Email
        org_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Organization the credential belongs to, present only on the redeeming poll.
          title: Org Id
        state:
          $ref: '#/components/schemas/CLIDeviceAuthorizationState'
          description: Lifecycle state observed by this poll.
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Approving user's ID, present only on the redeeming poll.
          title: User Id
      required:
      - state
      title: RedeemCLIDeviceCredentialResponse
      type: object
    CLIDeviceAuthorizationState:
      description: Lifecycle of one CLI device authorization.
      enum:
      - pending
      - approved
      - denied
      title: CLIDeviceAuthorizationState
      type: string
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http