Feathr API

openapi: 3.1.0
info:
  title: Feathr API
  version: '2026-10-27'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-27: 6 operation(s) read from 3 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Feathr has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 3
    documentation: 3
    pages-with-code: 2
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-27'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.feathr.co/webhooks
  - https://docs.feathr.co/getting-started
  - https://docs.feathr.co/authentication
servers:
- url: https://api.feathr.co
paths:
  /me:
    get:
      operationId: get_me
      tags:
      - Me
      summary: GET /me
      x-source: https://docs.feathr.co/getting-started
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMeResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://api.feathr.co/me \\ -H \"Authorization: Bearer $FEATHR_API_KEY\" \n GET /me returns the identity and scopes behind\
          \ the key — a quick way to\nconfirm your credentials work: \n { \"account_id\" : \"5f8e...c21a\" , \"scopes\" : [ \"persons:read\" ,\
          \ \"tags:write\" ] , \"key_id\" : \"6a1b...9f30\" } \n 3. Call an endpoint ​ \n List the persons in your account. GET /persons requires\
          \ at least one of\n updated_sinc"
  /persons:
    get:
      operationId: get_persons
      tags:
      - Persons
      summary: GET /persons
      x-source: https://docs.feathr.co/getting-started
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: string
      - name: size
        in: query
        required: false
        schema:
          type: string
      - name: updated_since
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPersonsResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl \"https://api.feathr.co/persons?updated_since=2024-01-01T00:00:00Z&page=1&size=50\" \\ -H \"Authorization: Bearer $FEATHR_API_KEY\"\
          \ \n The response is an offset-paginated Page envelope: \n { \"items\" : [ { \"id\" : \"...\" , \"email\" : \"...\" } ] , \"page\" :\
          \ 1 , \"size\" : 50 , \"total\" : 327 } \n Fetch the next page by incrementing page ; you've read everything once\n page * size >= total\
          \ . \n Next steps ​ \n Aut"
  /persons/{id}:
    get:
      operationId: get_persons_id
      tags:
      - Persons
      summary: GET /persons/{id}?extended=true returns. Note that a plain GET /persons/{id}, without extended=true, returns a smaller object.
      x-source: https://docs.feathr.co/webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: extended
        in: query
        required: false
        schema:
          type: boolean
        description: When true, returns the extended person view.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPersonsIdResponse'
      x-evidence:
        kind: documentation
  /webhooks:
    post:
      operationId: post_webhooks
      tags:
      - Webhooks
      summary: POST /webhooks
      x-source: https://docs.feathr.co/webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostWebhooksRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://api.feathr.co/webhooks \\ -H \"Authorization: Bearer $FEATHR_API_KEY\" \\ -H \"Content-Type: application/json\"\
          \ \\ -d '{ \"name\": \"crm-sync\", \"target_url\": \"https://hooks.example.com/feathr\", \"events\": [\"person.created\", \"person.updated\"\
          ] }' \n The response is the only place the full signing secret appears — store it now.\nLater reads return a masked hint ( whsec_…ab12\
          \ ). Lost it? POST "
  /webhooks/{id}:
    get:
      operationId: get_webhooks_id
      tags:
      - Webhooks
      summary: Sustained consecutive failures deactivate the subscription — check is_active and last_error on GET /webhooks/{id}.
      x-source: https://docs.feathr.co/webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /webhooks/{id}/rotate-secret:
    post:
      operationId: post_webhooks_id_rotate_secret
      tags:
      - Webhooks
      summary: Lost it? POST /webhooks/{id}/rotate-secret issues a new one.
      x-source: https://docs.feathr.co/webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostWebhooksIdRotateSecretResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetMeResponse:
      type: object
      properties:
        account_id:
          type: string
        scopes:
          type: array
          items:
            type: string
        key_id:
          type: string
    GetPersonsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              email:
                type: string
        page:
          type: integer
        size:
          type: integer
        total:
          type: integer
    GetPersonsIdResponse:
      type: object
      properties:
        id:
          type: string
        external_id:
          type: string
        email:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        name:
          type: string
        phone:
          type: string
        language:
          type: string
        pseudonym:
          type: string
        occupation:
          type: string
        companies:
          type: array
        address:
          type: object
        age:
          type: number
        ethnicity:
          type: string
        income:
          type: string
        edu:
          type: string
        tags:
          type: array
        tag_ids:
          type: array
        email_opt_out:
          type: boolean
        is_archived:
          type: boolean
        upsert_result:
          type: string
        0_person_url:
          type: string
        custom_fields:
          type: object
        custom_data:
          type: object
        date_created:
          type: string
        date_last_seen:
          type: string
    PostWebhooksRequest:
      type: object
      properties:
        name:
          type: string
        target_url:
          type: string
        events:
          type: array
          items:
            type: string
    PostWebhooksIdRotateSecretResponse:
      type: object
      properties:
        new_signing_secret:
          type: string
          description: The newly rotated signing secret.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Me
- name: Persons
- name: Webhooks