Algenta Auth API

openapi: 3.2.0
info:
  title: Algenta Ai Auth API
  version: 1.0.0
  description: 'Operations tagged Auth across 2 of this provider''s published API definitions: api.algenta.ai-openapi.json, gateway.algenta.ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.algenta.ai
- url: /
tags:
- name: Auth
paths:
  /v1/auth/signup:
    post:
      tags:
      - Auth
      summary: Create a new account
      description: Self-serve signup. Creates an organization, user account, and first API key in one step. The raw API key is shown **once** in the response — store it securely.
      operationId: signup_v1_auth_signup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignUpRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignUpResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/auth/login:
    post:
      tags:
      - Auth
      summary: Login and get a session token
      description: 'Returns a JWT bearer token valid for 7 days. Use as `Authorization: Bearer `.'
      operationId: login_v1_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/auth/verify:
    get:
      tags:
      - Auth
      summary: Verify email address via token link
      description: Verify a user's email address. Token sent on signup.
      operationId: verify_email_v1_auth_verify_get
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          description: Verification token from email
          title: Token
        description: Verification token from email
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Verify Email V1 Auth Verify Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/auth/forgot-password:
    post:
      tags:
      - Auth
      summary: Request a password reset email
      description: Send a password reset link to the user's email.
      operationId: forgot_password_v1_auth_forgot_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Forgot Password V1 Auth Forgot Password Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /v1/auth/reset-password:
    post:
      tags:
      - Auth
      summary: Complete password reset with token
      description: Reset a user's password using a valid reset token.
      operationId: reset_password_v1_auth_reset_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Reset Password V1 Auth Reset Password Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.algenta.ai
  /auth/signup:
    post:
      tags:
      - Auth
      summary: Create a new account
      description: Self-serve signup. Creates an organization, user account, and first API key in one step. The raw API key is shown **once** in the response — store it securely.
      operationId: _enforce_daily_email_signup_cap_auth_signup_post
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
          title: Email
      - name: redis
        in: query
        required: true
        schema:
          title: Redis
      - name: settings
        in: query
        required: true
        schema:
          title: Settings
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignUpResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: /
  /auth/login:
    post:
      tags:
      - Auth
      summary: Login and get a session token
      description: 'Returns a JWT bearer token valid for 7 days. Use as `Authorization: Bearer `.'
      operationId: login_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: /
  /auth/verify:
    get:
      tags:
      - Auth
      summary: Verify email address via token link
      description: Verify a user's email address. Token sent on signup.
      operationId: verify_email_auth_verify_get
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          description: Verification token from email
          title: Token
        description: Verification token from email
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                title: Response Verify Email Auth Verify Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: /
  /auth/forgot-password:
    post:
      tags:
      - Auth
      summary: Request a password reset email
      description: Send a password reset link to the user's email.
      operationId: forgot_password_auth_forgot_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Forgot Password Auth Forgot Password Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: /
  /auth/reset-password:
    post:
      tags:
      - Auth
      summary: Complete password reset with token
      description: Reset a user's password using a valid reset token.
      operationId: reset_password_auth_reset_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Reset Password Auth Reset Password Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: /
components:
  schemas:
    SignUpRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          maxLength: 128
          minLength: 8
          title: Password
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
      type: object
      required:
      - email
      - password
      - name
      title: SignUpRequest
    ForgotPasswordRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
      type: object
      required:
      - email
      title: ForgotPasswordRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    OrgInfo:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        slug:
          type: string
          title: Slug
        plan:
          type: string
          title: Plan
        status:
          type: string
          title: Status
        auto_fix_pipeline_enabled:
          type: boolean
          title: Auto Fix Pipeline Enabled
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - name
      - slug
      - plan
      - status
      - auto_fix_pipeline_enabled
      - created_at
      title: OrgInfo
    UserInfo:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        email:
          type: string
          title: Email
        name:
          type: string
          title: Name
        role:
          type: string
          title: Role
        email_verified:
          type: boolean
          title: Email Verified
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - email
      - name
      - role
      - email_verified
      - created_at
      title: UserInfo
    LoginRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          title: Password
      type: object
      required:
      - email
      - password
      title: LoginRequest
    ResetPasswordRequest:
      properties:
        token:
          type: string
          minLength: 1
          title: Token
        new_password:
          type: string
          maxLength: 128
          minLength: 8
          title: New Password
      type: object
      required:
      - token
      - new_password
      title: ResetPasswordRequest
    SignUpResponse:
      properties:
        user:
          $ref: '#/components/schemas/UserInfo'
        org:
          $ref: '#/components/schemas/OrgInfo'
        api_key:
          $ref: '#/components/schemas/APIKeyCreated'
        message:
          type: string
          title: Message
          default: Account created successfully. Your API key is shown once — store it securely.
      type: object
      required:
      - user
      - org
      - api_key
      title: SignUpResponse
    TokenResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        token_type:
          type: string
          title: Token Type
          default: bearer
        expires_in:
          type: integer
          title: Expires In
      type: object
      required:
      - access_token
      - expires_in
      title: TokenResponse
    APIKeyCreated:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        label:
          type: string
          title: Label
        key_prefix:
          type: string
          title: Key Prefix
        device_limit:
          type: integer
          minimum: 0.0
          title: Device Limit
          description: Max registered devices for this key on the local runtime path. 0 preserves the plan's unlimited or no-local-runtime behavior.
        raw_key:
          type: string
          title: Raw Key
          description: The full API key — shown ONCE, store it securely.
        created_at:
          type: string
          format: date-time
          title: Created At
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
      type: object
      required:
      - id
      - label
      - key_prefix
      - device_limit
      - raw_key
      - created_at
      title: APIKeyCreated
      description: Returned once at key creation — raw key shown here only.
    OrgInfo_2:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        slug:
          type: string
          title: Slug
        plan:
          type: string
          title: Plan
        status:
          type: string
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - name
      - slug
      - plan
      - status
      - created_at
      title: OrgInfo
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: 'Canonical v1 authentication. Use Authorization: Bearer <api_key>.'
    LegacyApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Legacy compatibility header for existing v1 clients.
x-refined-from:
- api.algenta.ai-openapi.json
- gateway.algenta.ai-openapi.json
x-canonical-mcp-endpoint: https://api.algenta.ai/mcp
x-primary-data-query-contract:
  api:
    contract_endpoint: /v1/meta/contract
    discovery_endpoint: /v1/data
    summary_endpoint: /v1/data/{dataset_id}/summary
    resolve_endpoint: /v1/resolve
    verify_endpoint: /v1/verify
    query_endpoint: /v1/query
    query_batch_endpoint: /v1/query/batch
    query_sql_report_endpoint: /v1/query/sql-report
  governed_filter_contract:
    kind: record_predicates
    time_filter_field: time_filter
    conditions_field: conditions
    selector_fields:
    - column
    - dimension_hint
    operators:
      scalar:
      - eq
      - gt
      - gte
      - lt
      - lte
      list:
      - in
      nullary:
      - is_null
      - is_not_null
    type_behavior:
      boolean:
      - eq
      string:
      - eq
      - in
      numeric:
      - eq
      - in
      - gt
      - gte
      - lt
      - lte
      null_checks:
      - is_null
      - is_not_null
    validation:
      requires_selector: true
      scalar_ops_require_value:
      - eq
      - gt
      - gte
      - lt
      - lte
      list_ops_require_non_empty_values:
      - in
      nullary_ops_forbid_value_and_values:
      - is_null
      - is_not_null
    applies_before_aggregation: true
    supports_non_sql_backends: true
    notes:
    - Filters apply to normalized source rows before aggregation and grouping.
    - Boolean equality uses eq.
    - This contract is database-agnostic and valid for Redis and other non-SQL backends after record normalization.
    - Nested OR groups, regex, text search, and arbitrary expressions are not part of this contract.
  direct_sdk:
    python:
      import_root: decision_engine
      preferred_client_class: AlgentaClient
      preferred_async_client_class: AsyncAlgentaClient
      compatibility_client_class: DecisionEngineClient
      compatibility_async_client_class: AsyncDecisionEngineClient
      contract_method: get_contract
      discovery_method: list_datasets
      summary_method: get_dataset_summary
      query_with_metadata_method: query_with_metadata
      query_batch_method: query_batch
      query_sql_report_method: query_sql_report
    typescript:
      import_package: algenta-sdk
      preferred_client_class: AlgentaClient
      compatibility_client_class: DecisionEngineClient
      contract_method: getContract
      discovery_method: listDatasets
      summary_method: getDatasetSummary
      query_with_metadata_method: queryWithMetadata
      query_batch_method: queryBatch
      query_sql_report_method: querySqlReport
  runtime_sdk:
    python:
      import_root: algenta
      runtime_class: Runtime
      libraries_entrypoint: libraries
      contract_method: get_contract
      discovery_method: list_datasets
      summary_method: get_dataset_summary
      query_with_metadata_method: query_with_metadata
      query_batch_method: query_batch
      query_sql_report_method: query_sql_report
    typescript:
      import_package: algenta-sdk
      runtime_class: Runtime
      libraries_entrypoint: libraries
      contract_method: getContract
      discovery_method: listDatasets
      summary_method: getDatasetSummary
      query_with_metadata_method: queryWithMetadata
      query_batch_method: queryBatch
      query_sql_report_method: querySqlReport
  cli:
    contract_command: de contract
    discovery_command: de data list --search <hint> --compact --limit <n>
    summary_command: de data summary <dataset_id>
    query_batch_command: de data query-batch <request.json>
    query_sql_report_command: de data sql-report <request.json>
    runtime_modules_command: de runtime modules
    runtime_functions_command: de runtime functions <module>
    runtime_execute_command: de runtime execute <module> <function> --args-json '<json>'
  mcp:
    contract_tool: get_contract
    discovery_tool: list_data
    summary_tool: get_data_summary
    query_tool: query_data
    query_batch_tool: query_batch
    query_sql_report_tool: query_sql_report
    runtime_library_list_tool: list_runtime_libraries
    runtime_library_execute_tool: execute_runtime_library
  recommended_flows:
    machine_readable_contract:
    - GET /v1/meta/contract
    governed_query:
    - GET /v1/data?search=...&compact=1
    - GET /v1/data/{dataset_id}/summary
    - POST /v1/resolve
    - POST /v1/verify
    - POST /v1/query
    multi_metric_query:
    - GET /v1/data?search=...&compact=1
    - GET /v1/data/{dataset_id}/summary
    - POST /v1/query/batch
    wide_sql_report:
    - GET /v1/data?search=...&compact=1
    - GET /v1/data/{dataset_id}/summary
    - POST /v1/query/sql-report
    decision_simulation_tools:
    - simulate — one scenario, full DecisionEnvelope (action, expected value, loss probability, percentiles); the run is recorded for list_runs.
    - plan_decision — same request as simulate but only the compact DecisionPlan summary; use when you do not need the full envelope.
    - score — one simulation plus a single weighted composite (expected_value/downside_risk weights) with score_breakdown; use to rank by one number.
    - compare — 2-10 named scenarios side by side; the winner is the highest expected value, with per-scenario deltas.
    - recommend — 2+ named actions ranked with a picked recommended_action, confidence, and rationale; use for 'which option should I pick'.
    - product_decision — plain business inputs (value with optional low/high) mapped for you; returns proceed/pause/reject with plain-English reasons; no simulation knowledge needed.
    dataset_onboarding_tools:
    - connect_data — the normal path for live sources (database/API/object storage) or uploads; returns a reusable dataset_id and supports refresh_data.
    - onboard_dataset — inline columns/records/CSV for semantic querying with background model training (track model_tier with list_datasets); no live connection.
    - 'register_source — the advanced path: full column profiling, formula detection, and join-key detection across registered sources (browse with list_data).'
    - list_data — browse datasets from the connect_data and register_source flows (connection_type, provider, refreshable).
    - list_datasets — browse semantically trained datasets with training status and model_tier.
x-capability-plane-contract:
  api:
    list_providers_endpoint: /v1/capability-providers
    get_provider_endpoint: /v1/capability-providers/{provider_id}
    list_bindings_endpoint: /v1/capability-bindings
    create_binding_endpoint: /v1/capability-bindings
    get_binding_endpoint: /v1/capability-bindings/{binding_id}
    update_binding_endpoint: /v1/capability-bindings/{binding_id}
    delete_binding_endpoint: /v1/capability-bindings/{binding_id}
    preview_test_binding_endpoint: /v1/capability-bindings/test
    test_binding_endpoint: /v1/capability-bindings/{binding_id}/test
    preview_discover_binding_endpoint: /v1/capability-bindings/discover
    discover_binding_endpoint: /v1/capability-bindings/{binding_id}/discover
    start_authorization_endpoint: /v1/capability-bindings/{binding_id}/authorize/start
    complete_authorization_endpoint: /v1/capability-bindings/{binding_id}/authorize/complete
    list_capabilities_endpoint: /v1/capabilities
    get_capability_endpoint: /v1/capabilities/{capability_id}
    route_capabilities_endpoint: /v1/capabilities/route
    execute_capability_endpoint: /v1/capabilities/execute
    record_outcome_endpoint: /v1/capabilities/outcomes
  enums:
    provider_types:
    - data_connector
    - mcp_provider
    - skill_pack
    - native_tool_pack
    - runtime_library_pack
    capability_kinds:
    - dataset
    - mcp_tool
    - mcp_resource
    - mcp_prompt
    - skill
    - native_tool
    - runtime_library
    implementation_kinds:
    - callable
    - instruction_only
    - hybrid
    execution_owners:
    - algenta_managed
    - client_managed
    binding_scopes:
    - user
    - workspace
    - organization
    binding_statuses:
    - unconfigured
    - authorizing
    - ready
    - degraded
    - quarantined
  direct_sdk:
    typescript:
      import_package: algenta-sdk
      preferred_client_class: AlgentaClient
      compatibility_client_class: DecisionEngineClient
      list_providers_method: listCapabilityProviders
      get_provider_method: getCapabilityProvider
      list_bindings_method: listCapabilityBindings
      create_binding_method: createCapabilityBinding
      get_binding_method: getCapabilityBinding
      update_binding_method: updateCapabilityBinding
      delete_binding_method: deleteCapabilityBinding
      preview_test_binding_method: previewTestCapabilityBinding
      test_binding_method: testCapabilityBinding
      preview_discover_binding_method: previewDiscoverCapabilityBinding
      discover_binding_method: discoverCapabilityBinding
      start_authorization_method: startCapabilityAuthorization
      complete_authorization_method: completeCapabilityAuthorization
      list_capabilities_method: listCapabilities
      get_capability_method: getCapability
      route_capabilities_method: routeCapabilities
      execute_capability_method: executeCapability
      record_outcome_method: recordCapabilityOutcome
      list_skills_method: listSkills
      enable_skill_method: enableSkill
      disable_skill_method: disableSkill
      list_mcp_providers_method: listMcpProviders
  runtime_sdk:
    typescript:
      import_package: algenta-sdk
      runtime_class: Runtime
      list_providers_method: listCapabilityProviders
      list_bindings_method: listCapabilityBindings
      list_capabilities_method: listCapabilities
      route_capabilities_method: routeCapabilities
      execute_capability_method: executeCapability
      register_adapter_method: registerCapabilityAdapter
  mcp:
    list_providers_tool: list_capability_providers
    list_bindings_tool: list_capability_bindings
    create_binding_tool: create_capability_binding
    test_binding_tool: test_capability_binding
    discover_binding_tool: discover_capability_binding
    list_capabilities_tool: list_capabilities
    get_capability_tool: get_capability
    route_capabilities_tool: route_capabilities
    execute_capability_tool: execute_capability
    list_skills_tool: list_skills
    enable_skill_tool: enable_skill
    disable_skill_tool: disable_skill
    compatibility_aliases:
    - list_data
    - get_data_summary
    - query_data
    - query_batch
    - query_sql_report
    - list_connectors
    - create_connector
    - test_connector
    - browse_connector
    - preview_test_connector
    - preview_browse_connector