openapi: 3.0.1
info:
  title: Pangea Security Services API
  description: >-
    Specification of representative Pangea security service APIs. Pangea exposes
    each security capability as its own REST service reachable at
    https://{service}.{csp}.{geo}.pangea.cloud (for example
    https://redact.aws.us.pangea.cloud). All requests are POST with a JSON body
    and are authenticated with a Bearer service token (or OAuth 2 access token)
    in the Authorization header. This document models several representative
    services - AuthN, Secure Audit Log, Redact, Vault, File Scan, IP Intel,
    Domain Intel, and AI Guard - and is not exhaustive of every endpoint or
    field.
  termsOfService: https://pangea.cloud/legal/terms-of-service/
  contact:
    name: Pangea Support
    url: https://pangea.cloud/contact/
  version: '1.0'
servers:
  - url: https://{service}.{csp}.{geo}.pangea.cloud
    description: Per-service Pangea host. Each service is reached at its own subdomain.
    variables:
      service:
        default: redact
        description: Service name (authn, audit, redact, vault, file-scan, ip-intel, domain-intel, ai-guard).
      csp:
        default: aws
        description: Cloud service provider hosting the service.
      geo:
        default: us
        description: Geographic region (us, eu).
security:
  - bearerAuth: []
tags:
  - name: AuthN
    description: Hosted authentication, user lifecycle, and session management.
  - name: Secure Audit Log
    description: Tamper-proof, cryptographically verifiable audit logging.
  - name: Redact
    description: Detect and remove sensitive information from text and structured data.
  - name: Vault
    description: Secrets and cryptographic key management.
  - name: File Scan
    description: Scan files for malicious content.
  - name: IP Intel
    description: IP reputation, geolocation, and VPN/proxy enrichment.
  - name: Domain Intel
    description: Domain and URL reputation lookups.
  - name: AI Guard
    description: Detect and redact malicious content in LLM inputs and outputs.
paths:
  /v2/user/create:
    servers:
      - url: https://authn.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: authnUserCreate
      tags:
        - AuthN
      summary: Create a user.
      description: Create a new user account in the project's AuthN instance.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateRequest'
      responses:
        '200':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/user/list:
    servers:
      - url: https://authn.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: authnUserList
      tags:
        - AuthN
      summary: List users.
      description: Look up users by scope and return a paginated list.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserListRequest'
      responses:
        '200':
          description: A page of users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/flow/start:
    servers:
      - url: https://authn.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: authnFlowStart
      tags:
        - AuthN
      summary: Start a sign-up / sign-in flow.
      description: Initiate a new authentication flow and return the available flow choices.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                cb_uri:
                  type: string
                  description: Callback URI for the redirect-based flow.
                email:
                  type: string
                flow_types:
                  type: array
                  items:
                    type: string
                    enum: [signin, signup]
      responses:
        '200':
          description: Flow started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/client/session/refresh:
    servers:
      - url: https://authn.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: authnClientSessionRefresh
      tags:
        - AuthN
      summary: Refresh a session.
      description: Refresh a session token using a refresh token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh_token]
              properties:
                refresh_token:
                  type: string
                user_token:
                  type: string
      responses:
        '200':
          description: Session refreshed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/log:
    servers:
      - url: https://audit.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: auditLog
      tags:
        - Secure Audit Log
      summary: Log an entry.
      description: Create a log entry in the Secure Audit Log.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditLogRequest'
      responses:
        '200':
          description: Entry logged with cryptographic proof material.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditLogResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/log:
    servers:
      - url: https://audit.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: auditLogBulk
      tags:
        - Secure Audit Log
      summary: Log multiple entries.
      description: Create up to 1000 log entries in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [events]
              properties:
                events:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  items:
                    $ref: '#/components/schemas/AuditEvent'
                verbose:
                  type: boolean
                config_id:
                  type: string
      responses:
        '200':
          description: Entries logged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/search:
    servers:
      - url: https://audit.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: auditSearch
      tags:
        - Secure Audit Log
      summary: Search the audit log.
      description: Search the Secure Audit Log and return matching, verifiable events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditSearchRequest'
      responses:
        '200':
          description: Search results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/root:
    servers:
      - url: https://audit.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: auditRoot
      tags:
        - Secure Audit Log
      summary: Get the Merkle tree root.
      description: Return the current root hash and consistency proof for verification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tree_size:
                  type: integer
                config_id:
                  type: string
      responses:
        '200':
          description: Root hash and proof.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/redact:
    servers:
      - url: https://redact.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: redactText
      tags:
        - Redact
      summary: Redact text.
      description: Redact sensitive information from provided text.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedactRequest'
      responses:
        '200':
          description: Redacted text and report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedactResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/redact_structured:
    servers:
      - url: https://redact.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: redactStructured
      tags:
        - Redact
      summary: Redact structured data.
      description: Redact sensitive information from structured data such as JSON.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [data]
              properties:
                data:
                  type: object
                  description: Structured content to redact.
                jsonp:
                  type: array
                  items:
                    type: string
                  description: JSON paths to fields to redact.
                format:
                  type: string
                rulesets:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Redacted structured data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/encrypt:
    servers:
      - url: https://vault.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: vaultEncrypt
      tags:
        - Vault
      summary: Encrypt data.
      description: Encrypt a message using a key stored in Vault.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultEncryptRequest'
      responses:
        '200':
          description: Cipher text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/decrypt:
    servers:
      - url: https://vault.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: vaultDecrypt
      tags:
        - Vault
      summary: Decrypt data.
      description: Decrypt cipher text using a key stored in Vault.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [id, cipher_text]
              properties:
                id:
                  type: string
                cipher_text:
                  type: string
                version:
                  type: integer
      responses:
        '200':
          description: Plain text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/secret/store:
    servers:
      - url: https://vault.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: vaultSecretStore
      tags:
        - Vault
      summary: Store a secret.
      description: Store a secret value in Vault.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [secret]
              properties:
                secret:
                  type: string
                name:
                  type: string
                folder:
                  type: string
      responses:
        '200':
          description: Secret stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PangeaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/scan:
    servers:
      - url: https://file-scan.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: fileScan
      tags:
        - File Scan
      summary: Scan a file.
      description: Scan a file for malicious content using the configured provider.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileScanRequest'
      responses:
        '200':
          description: Scan verdict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntelResponse'
        '202':
          description: Accepted - scan running asynchronously.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reputation:
    servers:
      - url: https://ip-intel.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: ipReputation
      tags:
        - IP Intel
      summary: Get IP reputation.
      description: Retrieve a reputation score and verdict for one or more IP addresses.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IpIntelRequest'
      responses:
        '200':
          description: Reputation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/geolocate:
    servers:
      - url: https://ip-intel.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: ipGeolocate
      tags:
        - IP Intel
      summary: Geolocate an IP.
      description: Retrieve geographic location information for one or more IP addresses.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IpIntelRequest'
      responses:
        '200':
          description: Geolocation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/reputation:
    servers:
      - url: https://domain-intel.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: domainReputation
      tags:
        - Domain Intel
      summary: Get domain reputation.
      description: Retrieve a reputation score and verdict for a domain.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  type: string
                provider:
                  type: string
                verbose:
                  type: boolean
                raw:
                  type: boolean
      responses:
        '200':
          description: Domain reputation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/text/guard:
    servers:
      - url: https://ai-guard.{csp}.{geo}.pangea.cloud
        variables:
          csp:
            default: aws
          geo:
            default: us
    post:
      operationId: aiGuardText
      tags:
        - AI Guard
      summary: Guard LLM text.
      description: >-
        Detect, remove, or block malicious content and intent in LLM inputs and
        outputs to prevent model manipulation and data leakage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiGuardRequest'
      responses:
        '200':
          description: Guard result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiGuardResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Pangea service token or OAuth 2 access token passed as a Bearer token.
  responses:
    Unauthorized:
      description: Missing or invalid authentication token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PangeaResponse'
  schemas:
    PangeaResponse:
      type: object
      description: Standard Pangea response envelope wrapping every service result.
      properties:
        request_id:
          type: string
        request_time:
          type: string
          format: date-time
        response_time:
          type: string
          format: date-time
        status:
          type: string
          example: Success
        summary:
          type: string
        result:
          type: object
    UserCreateRequest:
      type: object
      required: [email]
      properties:
        email:
          type: string
        profile:
          type: object
          additionalProperties:
            type: string
        username:
          type: string
    UserListRequest:
      type: object
      properties:
        filter:
          type: object
        last:
          type: string
        order:
          type: string
          enum: [asc, desc]
        size:
          type: integer
    UserResponse:
      allOf:
        - $ref: '#/components/schemas/PangeaResponse'
        - type: object
          properties:
            result:
              type: object
              properties:
                id:
                  type: string
                email:
                  type: string
                profile:
                  type: object
                verified:
                  type: boolean
                disabled:
                  type: boolean
    AuditEvent:
      type: object
      properties:
        message:
          type: string
          description: Main log message.
        actor:
          type: string
        action:
          type: string
        target:
          type: string
        status:
          type: string
        source:
          type: string
        timestamp:
          type: string
          format: date-time
    AuditLogRequest:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/AuditEvent'
        verbose:
          type: boolean
        signature:
          type: string
        public_key:
          type: string
        config_id:
          type: string
    AuditLogResponse:
      allOf:
        - $ref: '#/components/schemas/PangeaResponse'
        - type: object
          properties:
            result:
              type: object
              properties:
                hash:
                  type: string
                unpublished_root:
                  type: string
                membership_proof:
                  type: string
                consistency_proof:
                  type: array
                  items:
                    type: string
    AuditSearchRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        max_results:
          type: integer
        order:
          type: string
          enum: [asc, desc]
        config_id:
          type: string
    RedactRequest:
      type: object
      required: [text]
      properties:
        text:
          type: string
          description: The content to redact.
        config_id:
          type: string
        rules:
          type: array
          items:
            type: string
        rulesets:
          type: array
          items:
            type: string
        return_result:
          type: boolean
        debug:
          type: boolean
    RedactResponse:
      allOf:
        - $ref: '#/components/schemas/PangeaResponse'
        - type: object
          properties:
            result:
              type: object
              properties:
                redacted_text:
                  type: string
                count:
                  type: integer
                report:
                  type: object
    VaultEncryptRequest:
      type: object
      required: [id, plain_text]
      properties:
        id:
          type: string
          description: The ID of the key to use.
        plain_text:
          type: string
          description: Base64-encoded message to encrypt.
        version:
          type: integer
        additional_data:
          type: string
    FileScanRequest:
      type: object
      properties:
        provider:
          type: string
        verbose:
          type: boolean
        raw:
          type: boolean
        transfer_method:
          type: string
          enum: [direct, multipart, post-url, source-url]
        sha256:
          type: string
        size:
          type: integer
        source_url:
          type: string
    IpIntelRequest:
      type: object
      required: [ips]
      properties:
        ips:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: string
        provider:
          type: string
        verbose:
          type: boolean
        raw:
          type: boolean
    IntelResponse:
      allOf:
        - $ref: '#/components/schemas/PangeaResponse'
        - type: object
          properties:
            result:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    verdict:
                      type: string
                      example: malicious
                    score:
                      type: integer
                    category:
                      type: array
                      items:
                        type: string
                raw_data:
                  type: object
    AiGuardRequest:
      type: object
      properties:
        text:
          type: string
          description: Plain text input (up to 20 KiB).
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
              content:
                type: string
        recipe:
          type: string
          default: pangea_prompt_guard
        debug:
          type: boolean
          default: false
    AiGuardResponse:
      allOf:
        - $ref: '#/components/schemas/PangeaResponse'
        - type: object
          properties:
            result:
              type: object
              properties:
                blocked:
                  type: boolean
                transformed:
                  type: boolean
                recipe:
                  type: string
                detectors:
                  type: object
                  description: Per-detector analysis (prompt_injection, pii, secrets, malicious_entity).
                prompt_text:
                  type: string