startup-jobs Roles API

openapi: 3.2.0
info:
  title: Startup Jobs Roles API
  version: 1.0.0
  description: 'A free, read-only API for browsing jobs listed on startup.jobs.


    ## Authentication


    All endpoints (except this spec) require an API key. Create one for free at

    startup.jobs/account/api_keys and pass it

    as a bearer token:


    ```

    curl https://api.startup.jobs/v1/jobs -H "Authorization: Bearer sj_..."

    ```


    For quick experiments you can also pass it as an `api_key` query parameter.


    ## Attribution


    When you display jobs from this API, link the job title to the `url` field

    (a regular dofollow link, no `rel="nofollow"`) and credit Startup Jobs as the

    source. Full terms: https://startup.jobs/terms/api


    ## Freshness and coverage


    - The jobs list covers the last 14 days of listings.

    - New listings appear in the API 24 hours after they go live on startup.jobs,

    except jobs posted directly by employers, which appear immediately.

    - A company''s own jobs (`/v1/companies/{slug}/jobs`) are not limited to the

    14-day window, so you can embed a company''s full set of live listings.


    ## Full access


    Accounts with full API access are not limited to the 14-day window, can

    filter with `posted_before`, receive structured `salary_data` on each job,

    and get a higher rate limit. Email marc@startup.jobs to get full access.


    ## Rate limits


    20 requests per minute per API key (300 with full access). Exceeding the

    limit returns `429`. Contact support@startup.jobs if you need more.


    ## MCP server


    Prefer a conversational interface? Connect Claude, ChatGPT, or Cursor to

    our MCP server at `https://api.startup.jobs/mcp`: the same data as this

    API, plus job trends and salary benchmarks, without writing code.

    Details: https://startup.jobs/mcp


    ## Pagination


    List responses return at most 50 items per page. Use `next_cursor` from the

    response as the `starting_after` parameter of the next request until

    `has_more` is `false`.'
  contact:
    email: support@startup.jobs
    url: https://startup.jobs/api
  termsOfService: https://startup.jobs/terms/api
servers:
- url: https://api.startup.jobs
security:
- bearerAuth: []
tags:
- name: Roles
paths:
  /v1/roles:
    get:
      operationId: listRoles
      summary: List roles
      description: All role categories, usable as the `role` filter on `/v1/jobs`.
      responses:
        '200':
          description: All roles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Roles
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
    Role:
      type: object
      properties:
        title:
          type: string
        slug:
          type: string
        parent_slug:
          type:
          - string
          - 'null'
        url:
          type: string
          format: uri
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key created at https://startup.jobs/account/api_keys (starts with `sj_`).