philidor-io User agents API

openapi: 3.2.0
info:
  title: Philidor Io User agents API
  version: 1.2.0
  description: 'Operations tagged User agents 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: User agents
paths:
  /v1/users/{address}/agents:
    get:
      tags:
      - User agents
      summary: Get agents for a wallet
      description: Returns persisted agents and config for the given wallet. Requires a wallet signature over the message from GET /v1/users/{address}/agents/auth-message?method=GET. That message includes a single-use nonce valid for five minutes. Send it as base64 in x-philidor-agents-message and the hex signature in x-philidor-agents-signature. A message without the nonce is rejected with 401.
      parameters:
      - schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Wallet address (Ethereum)
        required: true
        name: address
        in: path
      - 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: Agents and config
          content:
            application/json:
              schema:
                type: object
                properties:
                  mainWalletName:
                    type: string
                  mainWalletPosition:
                    type: object
                    properties:
                      x:
                        type: number
                      y:
                        type: number
                    required:
                    - x
                    - y
                  linkWaypoints:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        x:
                          type: number
                        y:
                          type: number
                      required:
                      - x
                      - y
                  agents:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        evmAddress:
                          type: string
                        strategy:
                          type: string
                          enum:
                          - aggressive
                          - moderate
                          - conservative
                        rebalanceFrequency:
                          type: string
                          enum:
                          - daily
                          - weekly
                          - monthly
                        blacklist:
                          type: array
                          items:
                            type: string
                        whitelist:
                          type: array
                          items:
                            type: string
                        x:
                          type: number
                        y:
                          type: number
                      required:
                      - id
                      - name
                      - blacklist
                      - whitelist
                      - x
                      - y
                required:
                - agents
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          description: Missing or invalid signature
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '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: []
      operationId: getV1UsersAddressAgents
    put:
      tags:
      - User agents
      summary: Replace agents for a wallet
      description: 'Replaces persisted agents and config. When AGENT_VAULT_TERMS_REQUIRED is true, a stored acceptance of the current Agent Vault terms is required (POST /v1/users/{address}/terms); without it the response is 403 TERMS_NOT_ACCEPTED pointing at GET /v1/users/{address}/terms/auth-message. The flag defaults off, so PUT behaviour is unchanged until the agents app can POST terms and the flag is turned on for the Agent Vault release. A new terms version requires a new acceptance. Also requires a wallet signature over the message from GET /v1/users/{address}/agents/auth-message?method=PUT&bodySha256=. bodySha256 is the SHA-256 of the canonical JSON of the payload as sent — an object with only those of agents, linkWaypoints, mainWalletName, mainWalletPosition that the body carries, keys sorted recursively, undefined omitted. Include message and signature in the body with the payload. The nonce and Body-SHA256 are mandatory and the nonce is single-use: a message without them, a replay, or a body that does not match the signed hash is rejected with 401. The signature is checked before the terms gate, so a 403 has already consumed that agents nonce.'
      parameters:
      - schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Wallet address (Ethereum)
        required: true
        name: address
        in: path
      - 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.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  minLength: 1
                  description: Message signed by wallet (see docs)
                signature:
                  type: string
                  minLength: 1
                  description: EIP-191 signature (0x-prefixed)
                mainWalletName:
                  type: string
                mainWalletPosition:
                  type: object
                  properties:
                    x:
                      type: number
                    y:
                      type: number
                  required:
                  - x
                  - y
                linkWaypoints:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      x:
                        type: number
                      y:
                        type: number
                    required:
                    - x
                    - y
                agents:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                        description: Agent id (e.g. uuid)
                      name:
                        type: string
                        minLength: 1
                      evmAddress:
                        type:
                        - string
                        - 'null'
                      strategy:
                        type:
                        - string
                        - 'null'
                        enum:
                        - aggressive
                        - moderate
                        - conservative
                        - null
                      rebalanceFrequency:
                        type:
                        - string
                        - 'null'
                        enum:
                        - daily
                        - weekly
                        - monthly
                        - null
                      blacklist:
                        type: array
                        items:
                          type: string
                        default: []
                      whitelist:
                        type: array
                        items:
                          type: string
                        default: []
                      x:
                        type: number
                      y:
                        type: number
                    required:
                    - id
                    - name
                    - x
                    - y
                  default: []
              required:
              - message
              - signature
      responses:
        '200':
          description: Updated agents and config
          content:
            application/json:
              schema:
                type: object
                properties:
                  mainWalletName:
                    type: string
                  mainWalletPosition:
                    type: object
                    properties:
                      x:
                        type: number
                      y:
                        type: number
                    required:
                    - x
                    - y
                  linkWaypoints:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        x:
                          type: number
                        y:
                          type: number
                      required:
                      - x
                      - y
                  agents:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        evmAddress:
                          type: string
                        strategy:
                          type: string
                          enum:
                          - aggressive
                          - moderate
                          - conservative
                        rebalanceFrequency:
                          type: string
                          enum:
                          - daily
                          - weekly
                          - monthly
                        blacklist:
                          type: array
                          items:
                            type: string
                        whitelist:
                          type: array
                          items:
                            type: string
                        x:
                          type: number
                        y:
                          type: number
                      required:
                      - id
                      - name
                      - blacklist
                      - whitelist
                      - x
                      - y
                required:
                - agents
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '401':
          description: Missing or invalid signature
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: TERMS_NOT_ACCEPTED when AGENT_VAULT_TERMS_REQUIRED is true and the wallet has no stored acceptance of the current terms version. Fetch GET /v1/users/{address}/terms/auth-message and POST /v1/users/{address}/terms, then sign a new agents message. Not returned while that flag is off. WALLET_RESTRICTED when Agent Vault compliance enforcement screens a restricted wallet.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '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'
        '451':
          description: Caller jurisdiction is restricted (GEO_RESTRICTED). A known Tier A block says "Unavailable for legal reasons." UA or RU with no subdivision says "Location could not be verified."
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: Wallet screening is unavailable (SCREENING_UNAVAILABLE).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - {}
      - ApiKeyAuth: []
      operationId: putV1UsersAddressAgents
    servers:
    - url: https://api.philidor.io
      description: Production
    - url: http://localhost:3003
      description: Local
  /v1/users/{address}/agents/auth-message:
    get:
      tags:
      - User agents
      summary: Get auth message to sign
      description: 'Returns the message to sign for GET or PUT /v1/users/{address}/agents. Query: method=GET or method=PUT. For PUT, bodySha256 is required (SHA-256 hex of the canonical JSON of the payload as sent: only the fields present among agents, linkWaypoints, mainWalletName, mainWalletPosition, keys sorted recursively) so the signature covers the body; omitting it is a 400. The message carries a single-use nonce valid for five minutes. GET accepts only a message that includes that nonce; PUT accepts only a message that includes the nonce and Body-SHA256.'
      parameters:
      - schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Wallet address (Ethereum)
        required: true
        name: address
        in: path
      - schema:
          type: string
          enum:
          - GET
          - PUT
          default: GET
        required: false
        name: method
        in: query
      - schema:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
          description: SHA-256 hex of the canonical PUT payload. Required when method is PUT.
        required: false
        name: bodySha256
        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: Message to sign
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
        '400':
          description: method=PUT without bodySha256
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '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: []
      operationId: getV1UsersAddressAgentsAuthMessage
    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