philidor-io Security events API

openapi: 3.2.0
info:
  title: Philidor Io Security events API
  version: 1.2.0
  description: 'Operations tagged Security events across 2 of this provider''s published API definitions: philidor-openapi.json, philidor-io-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.philidor.io
  description: Production
- url: http://localhost:3003
  description: Local
tags:
- name: Security Events
paths:
  /v1/security-events/losses:
    get:
      operationId: listSecurityEventLosses
      tags:
      - Security Events
      summary: Loss board
      description: 'Rekt cases with a positive USD loss (DeFiLlama coverage baseline, enriched by other casebook sources), one row per incident with string ids such as rekt:defillama:…, plus coverage meta. The same body /v1/security-events?hasLoss=true returns; this route is the documented address. Filters: source (defillama), chainId, severity (low, medium, high, critical; legacy Info, Warning, Critical also accepted), search (max 200 characters), sort=loss, minLossUsd and affectsTrackedUniverse. Pages beyond 10000 or invalid enum filters return an empty page with global coverage metadata; no page query is executed.'
      parameters:
      - schema:
          type: integer
          description: Page number (default 1)
          example: 1
        required: false
        name: page
        in: query
      - schema:
          type: integer
          description: Items per page (default 50, clamped to 1–100)
          example: 50
        required: false
        name: limit
        in: query
      - schema:
          type: string
          description: Only defillama is a loss-board source
        required: false
        name: source
        in: query
      - schema:
          type: integer
          description: Chain id filter; invalid values are ignored
        required: false
        name: chainId
        in: query
      - schema:
          type: string
          description: low, medium, high or critical (casebook severity); legacy Info, Warning or Critical also accepted. Unknown values return an empty page.
          enum:
          - low
          - medium
          - high
          - critical
          - Info
          - Warning
          - Critical
        required: false
        name: severity
        in: query
      - schema:
          type: string
          description: Case-insensitive substring over title and description
        required: false
        name: search
        in: query
      - schema:
          type: string
          description: '''loss'' orders by loss_usd; anything else by date'
        required: false
        name: sort
        in: query
      - schema:
          type: string
          description: Nonnegative USD loss threshold; invalid values are ignored
        required: false
        name: minLossUsd
        in: query
      - schema:
          type: string
          description: '''true'' keeps incidents touching tracked vaults only'
        required: false
        name: affectsTrackedUniverse
        in: query
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
        description: Optional correlation id, echoed unchanged when valid; otherwise a UUID is generated.
      responses:
        '200':
          description: Loss board
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        source:
                          type: string
                        sourceId:
                          type: string
                        chainId:
                          type: integer
                        chainSlug:
                          type: string
                        onchainId:
                          type: string
                        title:
                          type: string
                        description:
                          type:
                          - string
                          - 'null'
                        poster:
                          type:
                          - string
                          - 'null'
                        attackers:
                          type: array
                          items:
                            type: string
                        victims:
                          type: array
                          items:
                            type: string
                        netScore:
                          type: integer
                        confirmations:
                          type: integer
                        disconfirmations:
                          type: integer
                        lossAmountUsd:
                          type:
                          - number
                          - 'null'
                        severity:
                          type: string
                        txHash:
                          type:
                          - string
                          - 'null'
                        nativeUrl:
                          type:
                          - string
                          - 'null'
                        links:
                          type: array
                          items:
                            type: object
                            properties:
                              label:
                                type: string
                              url:
                                type: string
                              kind:
                                type: string
                            required:
                            - label
                            - url
                        affectsTrackedUniverse:
                          type: boolean
                        attackedAt:
                          type:
                          - string
                          - 'null'
                        promotedEventId:
                          type:
                          - integer
                          - 'null'
                        classification:
                          type:
                          - string
                          - 'null'
                        technique:
                          type:
                          - string
                          - 'null'
                        mechanism:
                          type:
                          - string
                          - 'null'
                        targetType:
                          type:
                          - string
                          - 'null'
                        chains:
                          type: array
                          items:
                            type: string
                        bridgeHack:
                          type: boolean
                        language:
                          type:
                          - string
                          - 'null'
                        returnedFundsUsd:
                          type:
                          - number
                          - 'null'
                        protocolSlug:
                          type:
                          - string
                          - 'null'
                        protocolLogo:
                          type:
                          - string
                          - 'null'
                        protocolCategory:
                          type:
                          - string
                          - 'null'
                        incidentDossier:
                          type: object
                          properties:
                            rootCause:
                              type:
                              - string
                              - 'null'
                            transactions:
                              type: array
                              items:
                                type: object
                                properties:
                                  hash:
                                    type: string
                                  explorerUrl:
                                    type: string
                                  network:
                                    type:
                                    - string
                                    - 'null'
                                  label:
                                    type: string
                                required:
                                - hash
                                - explorerUrl
                                - network
                                - label
                            addresses:
                              type: array
                              items:
                                type: object
                                properties:
                                  address:
                                    type: string
                                  explorerUrl:
                                    type:
                                    - string
                                    - 'null'
                                  role:
                                    type: string
                                  label:
                                    type: string
                                required:
                                - address
                                - explorerUrl
                                - role
                                - label
                            sources:
                              type: array
                              items:
                                type: object
                                properties:
                                  label:
                                    type: string
                                  url:
                                    type: string
                                  kind:
                                    type: string
                                required:
                                - label
                                - url
                                - kind
                            relatedNews:
                              type: array
                              items:
                                type: object
                                properties:
                                  title:
                                    type: string
                                  url:
                                    type: string
                                  publishedAt:
                                    type: string
                                required:
                                - title
                                - url
                                - publishedAt
                            coverage:
                              type: object
                              properties:
                                transactionStatus:
                                  type: string
                                transactionCount:
                                  type: integer
                                addressCount:
                                  type: integer
                                sourceCount:
                                  type: integer
                                newsCount:
                                  type: integer
                              required:
                              - transactionStatus
                              - transactionCount
                              - addressCount
                              - sourceCount
                              - newsCount
                            provenance:
                              type:
                              - object
                              - 'null'
                              properties:
                                provider:
                                  type: string
                                providerUrl:
                                  type:
                                  - string
                                  - 'null'
                                matchedTitle:
                                  type:
                                  - string
                                  - 'null'
                                matchMethod:
                                  type:
                                  - string
                                  - 'null'
                                matchConfidence:
                                  type:
                                  - number
                                  - 'null'
                                extractedAt:
                                  type:
                                  - string
                                  - 'null'
                              required:
                              - provider
                              - providerUrl
                              - matchedTitle
                              - matchMethod
                              - matchConfidence
                              - extractedAt
                          required:
                          - rootCause
                          - transactions
                          - addresses
                          - sources
                          - relatedNews
                          - coverage
                          - provenance
                      required:
                      - id
                      - source
                      - sourceId
                      - chainId
                      - chainSlug
                      - onchainId
                      - title
                      - description
                      - poster
                      - attackers
                      - victims
                      - netScore
                      - confirmations
                      - disconfirmations
                      - lossAmountUsd
                      - severity
                      - txHash
                      - nativeUrl
                      - links
                      - affectsTrackedUniverse
                      - attackedAt
                      - promotedEventId
                      - classification
                      - technique
                      - mechanism
                      - targetType
                      - chains
                      - bridgeHack
                      - language
                      - returnedFundsUsd
                      - protocolSlug
                      - protocolLogo
                      - protocolCategory
                      - incidentDossier
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      hasMore:
                        type: boolean
                      total:
                        type: integer
                      totalLossUsd:
                        type: number
                      coverageSource:
                        type: string
                      coverageTotal:
                        type: integer
                      coverageTotalLossUsd:
                        type: number
                      coverageRefreshedAt:
                        type:
                        - string
                        - 'null'
                      evidenceCoveredIncidents:
                        type: integer
                      transactionCoveredIncidents:
                        type: integer
                      evidenceRefreshedAt:
                        type:
                        - string
                        - 'null'
                    required:
                    - page
                    - limit
                    - hasMore
                    - total
                    - totalLossUsd
                    - coverageSource
                    - coverageTotal
                    - coverageTotalLossUsd
                    - coverageRefreshedAt
                    - evidenceCoveredIncidents
                    - transactionCoveredIncidents
                    - evidenceRefreshedAt
                required:
                - data
                - meta
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '429':
          description: Rate limit exceeded; retry after Retry-After seconds
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - {}
      - ApiKeyAuth: []
    servers:
    - url: https://api.philidor.io
      description: Production
    - url: http://localhost:3003
      description: Local
  /v1/security-events:
    get:
      operationId: listSecurityEvents
      tags:
      - Security Events
      summary: Published security events
      description: The published broad feed (thatsRekt and other sources) with source, chain, severity and search filters. Rows are published by an editor (published_by=admin) or by the auto-publish pass for incidents that touch the tracked universe or carry a USD loss (published_by=auto). With hasLoss=true the loss board is returned instead (rekt cases with a USD loss, DeFiLlama coverage meta; also at /v1/security-events/losses). page and limit fall back to their defaults on invalid input; limit is clamped to 100; an unknown sort falls back to attacked_at. Invalid enum filters, search over 200 characters, source over 64 characters or page beyond 10000 return an empty page. Loss-board coverage metadata is retained without executing the page query. Registry severity accepts Info, Warning or Critical; hasLoss=true also accepts low, medium, high or critical. The registry always has published_only semantics; drafts are never exposed.
      parameters:
      - schema:
          type: integer
          description: Page number (default 1)
          example: 1
        required: false
        name: page
        in: query
      - schema:
          type: integer
          description: Items per page (default 50, clamped to 1–100)
          example: 50
        required: false
        name: limit
        in: query
      - schema:
          type: string
          description: Source filter, e.g. thatsrekt
        required: false
        name: source
        in: query
      - schema:
          type: integer
          description: Chain id filter; invalid values are ignored
        required: false
        name: chainId
        in: query
      - schema:
          type: string
          description: 'Registry: Info, Warning or Critical. With hasLoss=true: low, medium, high or critical; legacy registry labels also accepted. Unknown values return an empty page.'
          enum:
          - low
          - medium
          - high
          - critical
          - Info
          - Warning
          - Critical
        required: false
        name: severity
        in: query
      - schema:
          type: string
          description: Case-insensitive substring over title and description
        required: false
        name: search
        in: query
      - schema:
          type: string
          description: '''loss'' orders by loss_amount_usd; anything else by attacked_at'
        required: false
        name: sort
        in: query
      - schema:
          type: string
          description: '''true'' keeps events touching tracked vaults only'
        required: false
        name: affectsTrackedUniverse
        in: query
      - schema:
          type: string
          description: '''admin'' keeps rows an editor published by hand; ''auto'' those the auto-publish pass published (PHI-297)'
        required: false
        name: published_by
        in: query
      - schema:
          type: string
          description: '''true'' returns the loss board (see /v1/security-events/losses)'
        required: false
        name: hasLoss
        in: query
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
        description: Optional correlation id, echoed unchanged when valid; otherwise a UUID is generated.
      responses:
        '200':
          description: Security events (or the loss board with hasLoss=true)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      hasMore:
                        type: boolean
                    required:
                    - page
                    - limit
                    - hasMore
                required:
                - data
                - meta
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '429':
          description: Rate limit exceeded; retry after Retry-After seconds
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - {}
      - ApiKeyAuth: []
    servers:
    - url: https://api.philidor.io
      description: Production
    - url: http://localhost:3003
      description: Local
components:
  headers:
    Retry-After:
      description: Seconds to wait before retrying (429, 503, 504).
      schema:
        type: integer
        minimum: 0
    X-RateLimit-Limit:
      description: Requests allowed in the active window for this caller.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix timestamp (seconds) when the window resets.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in the active window.
      schema:
        type: integer
    X-Request-Id:
      description: Correlation id for the request. A valid inbound X-Request-Id (1-64 word characters or dashes) is echoed; otherwise one is generated. Quote it when reporting a failure.
      schema:
        type: string
  schemas:
    ErrorEnvelope:
      description: Error body. `legacy_code` is present for one compatibility release when an older endpoint previously emitted a lowercase route-specific code.
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          properties:
            code:
              type: string
              pattern: ^[A-Z][A-Z0-9_]*$
              example: NOT_FOUND
            message:
              type: string
              example: Vault not found
            request_id:
              type: string
              description: Correlation id, also in the X-Request-Id header.
            legacy_code:
              type: string
              description: Previous lowercase code during the one-release migration window.
            pricing_url:
              type: string
              description: Present on a tier gate. Same URL as refusal.upgrade_url.
            refusal:
              description: Present on 401/403 for a gated data family (PHI-312). Same object as one row of GET /v1/access/families. x402_price is null until pay-per-request is live.
              type: object
              required:
              - restricted_fields
              - family
              - required_plan
              - upgrade_url
              - x402_price
              properties:
                restricted_fields:
                  type: array
                  items:
                    type: string
                family:
                  type: string
                required_plan:
                  type:
                  - string
                  - 'null'
                  enum:
                  - Free
                  - Analyst
                  - Pro
                  - Data
                  - Decisioning
                  - Embedded
                  - null
                upgrade_url:
                  type: string
                  example: https://philidor.io/pricing
                x402_price:
                  type: 'null'
          additionalProperties: true
  securitySchemes:
    IndexTokenAuth:
      type: http
      scheme: bearer
      description: Separate index preview/client token. Commercial API keys do not unlock private index routes.
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Philidor API key (`Authorization: Bearer pk_live_...`). Optional on public endpoints, where it raises rate limits and unlocks tiered capabilities. The administrative surfaces additionally require operator-set metadata.admin_surface=true; mutations require metadata.admin_role=admin_editor or admin_operator under the same write-role enforcement as admin sessions. A plan tier alone never grants administrative access.'
    AdminCookieAuth:
      type: apiKey
      in: cookie
      name: philidor_admin_session
      description: Administrative session. Additionally IP-allowlisted.
    DashboardCookieAuth:
      type: apiKey
      in: cookie
      name: philidor_dashboard_session
      description: Dashboard session cookie (httpOnly).
x-refined-from:
- philidor-openapi.json
- philidor-io-openapi.json