githunt-ai Lists API

openapi: 3.2.0
info:
  title: GitHunt Lists API
  version: 1.0.0
  description: 'Search, look up, and analyze GitHub developers programmatically. GitHunt gives you millisecond access to millions of developers available on GitHub - ranked, scored, and with contact details where publicly available. Every request is billed against your plan''s monthly API call quota; all plans are additionally capped at 2000 calls/day.

    Quotas: Free 50 calls/month (trial), Pro 1000 calls/month, Team 1500 calls/month (unused credits roll over, up to one extra month''s allowance), Enterprise unlimited. Endpoints cost different amounts of quota: search 1 credit, get user 1 credit, evidence report 3 credits (0 when the report is still pending), analyze profile 3 credits, and every /v1/lists operation 0 credits. Endpoints that debit 0 credits still count against the daily cap.'
  contact:
    email: support@githunt.ai
servers:
- url: https://api.githunt.ai
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Lists
paths:
  /v1/lists/{name}/logins:
    post:
      operationId: addSeenLogins
      summary: Record reviewed or delivered logins on a seen list
      description: 'Idempotent write. The list is created on first write, subject to the plan''s list cap (free 1, pro 5, team 50, enterprise 200). Lists are owned by the account behind the API key, so rotating a key keeps the history and another account cannot reach it. Debits 0 monthly credits.


        Call it with an empty or omitted `logins` array to create the list without marking anyone seen - the explicit "open a brief" call, so a fresh run can use `excludeList` and claims before it has a first candidate. `POST /v1/lists/{name}/claims` also creates the list on first use.'
      parameters:
      - $ref: '#/components/parameters/ListName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                logins:
                  type: array
                  items:
                    type: string
                  minItems: 0
                  maxItems: 500
                  description: GitHub logins, lowercased and deduped server-side. An over-cap or malformed list is rejected, never truncated. Empty or omitted creates the list and records nobody.
                githubIds:
                  type: object
                  additionalProperties:
                    type: string
                  description: 'Optional `{ login: githubId }` map for stable identity dedup across renames. Non-string values are dropped.'
      responses:
        '200':
          description: Write result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWriteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Lists
    delete:
      operationId: removeSeenLogins
      summary: Remove logins from a seen list
      description: Debits 0 monthly credits. Unknown list names return `not_found`.
      parameters:
      - $ref: '#/components/parameters/ListName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - logins
              properties:
                logins:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 500
      responses:
        '200':
          description: Removal result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      removed:
                        type: integer
                        description: Entries that existed and were deleted.
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Lists
  /v1/lists/{name}:
    get:
      operationId: getSeenList
      summary: One page of a seen list
      description: Debits 0 monthly credits.
      parameters:
      - $ref: '#/components/parameters/ListName'
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Opaque cursor from a previous page's `next_cursor`.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 100
        description: Entries per page. Values above 200 are clamped.
      responses:
        '200':
          description: One page of entries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Lists
    delete:
      operationId: deleteSeenList
      summary: Delete a seen list and all its entries
      description: Debits 0 monthly credits.
      parameters:
      - $ref: '#/components/parameters/ListName'
      responses:
        '200':
          description: Deletion result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      name:
                        type: string
                      deleted:
                        type: integer
                        description: Entries removed with the list.
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Lists
  /v1/lists/{name}/claims:
    post:
      operationId: claimSeenLogins
      summary: Atomically claim logins for one run
      description: Reserves identities so two runs on the same brief cannot deliver the same candidate. A login is claimable when it is not on the list or its previous claim has expired; `seen` entries and live claims come back as `unavailable` instead of being stolen. Claims expire, so an interrupted run releases its candidates and the next search can return them again. The list is created on first claim under the same plan cap as `POST /v1/lists/{name}/logins`, so a fresh brief needs no prior write; exceeding the cap is an `invalid_request`. Debits 0 monthly credits.
      parameters:
      - $ref: '#/components/parameters/ListName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - logins
              properties:
                logins:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
                ttlSeconds:
                  type: integer
                  minimum: 60
                  maximum: 3600
                  default: 900
                  description: Claim lifetime. Out-of-range values are clamped.
      responses:
        '200':
          description: Claim result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
      tags:
      - Lists
components:
  schemas:
    ClaimResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            name:
              type: string
            claimed:
              type: array
              items:
                type: string
              description: Logins this run now holds until `claim_expires_at`.
            unavailable:
              type: array
              description: Logins another run holds, or that are already `seen`.
              items:
                type: object
                properties:
                  login:
                    type: string
                  state:
                    type: string
                    enum:
                    - seen
                    - claimed
                  claim_expires_at:
                    type: string
                    nullable: true
            claim_expires_at:
              type: string
              format: date-time
        meta:
          $ref: '#/components/schemas/Meta'
    ListPageResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            name:
              type: string
            total:
              type: integer
            entries:
              type: array
              items:
                $ref: '#/components/schemas/SeenListEntry'
            next_cursor:
              type: string
              nullable: true
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - quota_exceeded
              - invalid_request
              - not_found
              - internal
            message:
              type: string
    ListWriteResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            name:
              type: string
            added:
              type: integer
              description: Logins that were not already on the list.
            existing:
              type: integer
              description: Logins already present. An existing claim is upgraded to `seen` and loses its expiry, so replaying a partial run is safe.
            total:
              type: integer
              description: Entries on the list after this write.
        meta:
          $ref: '#/components/schemas/Meta'
    Quota:
      type: object
      properties:
        used:
          type: integer
        limit:
          type: integer
          description: -1 means unlimited
        month:
          type: string
          example: 2026-07
        cost:
          type: integer
          description: 'Credits this request debited (search: 1, get user: 1, evidence report: 3 when a report is returned and 0 while pending, analyze profile: 3, list operations: 0). `used` already reflects this charge.'
          example: 1
        rollover:
          type: integer
          description: Unused credits banked from the previous month and available on top of `limit` this month (`remaining` = limit + rollover - used). Only present on the Team plan, capped at one extra month's allowance (so at most 2x the allowance is usable in a month).
          example: 340
    Meta:
      type: object
      description: Envelope metadata. `quota.cost` is 0 on endpoints that debit no credits.
      properties:
        requestId:
          type: string
        quota:
          $ref: '#/components/schemas/Quota'
    SeenListEntry:
      type: object
      properties:
        login:
          type: string
        state:
          type: string
          enum:
          - seen
          - claimed
          description: '`seen` entries are permanent. `claimed` entries hold an expiring reservation and become claimable again when it lapses, so an interrupted run does not lose its candidates. A `claimed` entry with a past `claim_expires_at` is still listed here, but it no longer excludes its candidate from search.'
        added_at:
          type: string
          nullable: true
        claim_expires_at:
          type: string
          nullable: true
  responses:
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing, invalid, or revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    QuotaExceeded:
      description: Monthly or daily quota exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the quota resets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: No matching developer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  parameters:
    ListName:
      name: name
      in: path
      required: true
      schema:
        type: string
        pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
      example: vami-scala-payments
      description: Seen list name, 1-64 characters of a-z, 0-9, "-" or "_", starting with a letter or digit. Trimmed and lowercased server-side.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer ghk_live_...'
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key