find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/ayhire-com:ayhire-com-watching-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Ayhire Com Watching API
  version: 1.0.0
  contact:
    name: AyHire
    url: https://ayhire.com
  description: 'Operations tagged Watching across 2 of this provider''s published API definitions: ayhire-com-openapi.json, ayhire-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://ayhire.com
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Watching
  description: People a workspace wants to hear about, and what changed.
paths:
  /api/activity:
    get:
      operationId: listActivity
      summary: What changed, newest first
      description: New matches, availability changes, changes in people you watch, and roles they may fit.
      tags:
      - Watching
      parameters:
      - name: workspace
        in: query
        description: Which of your workspaces, by id or name. The current one when left out.
        schema:
          type: string
      - name: limit
        in: query
        description: 1-100
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: kinds
        in: query
        description: 'Comma-separated: new_matches, availability_changed, watch_signal, fits_role. Unknown ones are ignored.'
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityEvent'
                required:
                - events
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://ayhire.com
  /api/activity/{id}/add-to-role:
    post:
      operationId: addSuggestionToRole
      summary: Add the person in a may-fit suggestion to its role
      description: 'Someone already in the role is left as they are: `{ added: false, already: true }`.'
      tags:
      - Watching
      parameters:
      - name: id
        in: path
        required: true
        description: A fits_role suggestion's id (a UUID) from GET /api/activity
        schema:
          type: string
      - name: workspace
        in: query
        description: Which of your workspaces, by id or name. The current one when left out.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  added:
                    type: boolean
                  already:
                    type: boolean
                  role:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      title:
                        type: string
                  github_username:
                    type: string
                  href:
                    type: string
                required:
                - added
                - already
                - role
                - github_username
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://ayhire.com
  /api/notifications:
    get:
      operationId: getEmailAlerts
      summary: Your email choice for watch alerts
      tags:
      - Watching
      parameters:
      - name: workspace
        in: query
        description: Which of your workspaces, by id or name. The current one when left out.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspace:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                  email:
                    type: string
                    enum:
                    - 'off'
                    - instant
                    - daily
                  address:
                    type:
                    - string
                    - 'null'
                  configured:
                    type: boolean
                required:
                - email
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      operationId: setEmailAlerts
      summary: Choose email alerts for watch changes
      description: 'instant: at most one email an hour; daily: at most one a day.'
      tags:
      - Watching
      parameters:
      - name: workspace
        in: query
        description: Which of your workspaces, by id or name. The current one when left out.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  enum:
                  - 'off'
                  - instant
                  - daily
              required:
              - email
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspace:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                  email:
                    type: string
                    enum:
                    - 'off'
                    - instant
                    - daily
                  address:
                    type:
                    - string
                    - 'null'
                  configured:
                    type: boolean
                required:
                - email
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://ayhire.com
  /api/watches:
    get:
      operationId: listWatches
      summary: Everyone the workspace watches
      description: With what each watch is for, the last check, the latest change, and open roles they may fit.
      tags:
      - Watching
      parameters:
      - name: workspace
        in: query
        description: Which of your workspaces, by id or name. The current one when left out.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspace:
                    oneOf:
                    - type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        name:
                          type: string
                    - type: 'null'
                  watches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Watch'
                  count:
                    type: integer
                  max:
                    type: integer
                  paid:
                    type: object
                    properties:
                      available:
                        type: boolean
                      note:
                        type:
                        - string
                        - 'null'
                required:
                - watches
                - count
                - max
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://ayhire.com
  /api/watches/{username}:
    get:
      operationId: getWatch
      summary: One watch
      tags:
      - Watching
      parameters:
      - name: username
        in: path
        required: true
        description: A GitHub username
        schema:
          type: string
      - name: workspace
        in: query
        description: Which of your workspaces, by id or name. The current one when left out.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  watch:
                    oneOf:
                    - $ref: '#/components/schemas/Watch'
                    - type: 'null'
                  linkedin_known:
                    type: boolean
                  count:
                    type: integer
                  max:
                    type: integer
                  paid:
                    type: object
                    properties:
                      available:
                        type: boolean
                      note:
                        type:
                        - string
                        - 'null'
                required:
                - watch
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      operationId: watchPerson
      summary: Watch someone, or change what a watch is for
      description: AyHire re-checks their public GitHub every day. A new watch gets every rule; an existing one changes only the fields sent.
      tags:
      - Watching
      parameters:
      - name: username
        in: path
        required: true
        description: A GitHub username
        schema:
          type: string
      - name: workspace
        in: query
        description: Which of your workspaces, by id or name. The current one when left out.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rules:
                  type: array
                  items:
                    type: string
                    enum:
                    - open_to_work
                    - job_change
                    - says_looking
                    - new_work
                  minItems: 1
                  maxItems: 4
                  uniqueItems: true
                paid_checks:
                  type: boolean
                  description: Also re-read their LinkedIn every 2 weeks (paid)
                role_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
                  description: The role it was started from
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  watch:
                    $ref: '#/components/schemas/Watch'
                  created:
                    type: boolean
                required:
                - watch
                - created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      operationId: unwatchPerson
      summary: Stop watching someone
      description: Idempotent.
      tags:
      - Watching
      parameters:
      - name: username
        in: path
        required: true
        description: A GitHub username
        schema:
          type: string
      - name: workspace
        in: query
        description: Which of your workspaces, by id or name. The current one when left out.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                required:
                - deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    servers:
    - url: https://ayhire.com
components:
  responses:
    NotFound:
      description: Nothing with that id, or not on your account (code not_found)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: No API key, or a revoked one (code unauthorized)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is not valid (code validation_error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: An hourly or per-minute limit is spent; the message says when it resets (code rate_limited or github_rate_limited)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Not allowed for this caller, e.g. a workspace member where an owner is needed (code forbidden)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Something failed on AyHire's side (code internal_error)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: What went wrong, in a sentence
        code:
          type: string
          description: Stable code to branch on
          enum:
          - unauthorized
          - forbidden
          - not_found
          - payment_required
          - rate_limited
          - github_rate_limited
          - validation_error
          - internal_error
        hint:
          type: string
          description: What to do about it, when there is something
      required:
      - error
      - code
    Watch:
      type: object
      properties:
        github_username:
          type: string
        name:
          type:
          - string
          - 'null'
        avatar_url:
          type:
          - string
          - 'null'
        role:
          oneOf:
          - type: object
            properties:
              id:
                type: string
                format: uuid
              title:
                type: string
          - type: 'null'
        rules:
          type: array
          items:
            type: string
            enum:
            - open_to_work
            - job_change
            - says_looking
            - new_work
        paid_checks:
          type: boolean
          description: Also re-read their LinkedIn every 2 weeks (paid)
        created_at:
          type: string
          format: date-time
        last_checked_at:
          type:
          - string
          - 'null'
        last_check_status:
          type:
          - string
          - 'null'
          enum:
          - ok
          - not_found
          - failed
          - null
        latest:
          type:
          - object
          - 'null'
          description: The newest change, in a sentence, with its evidence link
        fits:
          type: array
          items:
            type: object
            properties:
              event_id:
                type: string
                format: uuid
              role_id:
                type: string
                format: uuid
              role_title:
                type: string
              relevance:
                type: integer
              reason:
                type: string
              added:
                type: boolean
      required:
      - github_username
      - rules
    ActivityEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
          - new_matches
          - availability_changed
          - watch_signal
          - fits_role
        role_id:
          type:
          - string
          - 'null'
        role_title:
          type:
          - string
          - 'null'
        github_username:
          type:
          - string
          - 'null'
        payload:
          type: object
          properties: {}
          description: Depends on kind
        created_at:
          type: string
          format: date-time
      required:
      - id
      - kind
      - created_at
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ayh_ API key
      description: 'An AyHire API key: Authorization: Bearer ayh_...'
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: The same AyHire API key, in x-api-key
externalDocs:
  description: AyHire for agents
  url: https://ayhire.com/agents.md
x-refined-from:
- ayhire-com-openapi.json
- ayhire-com-openapi.yml