stophy-dev Endpoints API

openapi: 3.2.0
info:
  title: Stophy Endpoints API
  version: '1'
  description: 'Every endpoint is a POST that takes its input as a JSON object body. Unknown fields are rejected with 400.


    Responses leave out empty values: null, empty strings, empty objects and empty nested lists are not sent.


    Text comes back whole. To get shorter responses, add ?maxTextLength= to the URL. Every text value longer than that is cut and ends with …. A screenshot is never cut, and a page whose text was cut has isTruncated set to true.


    x-credits is what one call costs. Every call costs the same, whatever it returns, unless an operation''s description says it costs per 10 results, or per second of audio. Then x-credits is the lowest price and x-credits-max the most one call can cost. Where an operation takes limit, send it to return fewer results and pay for fewer.


    When a response has a cursor, send it back unchanged with the same input to get the next page. When it has a page, send the next page number.


    Endpoints whose security includes {} also work without an API key: 10 requests a minute and 50 a day per IP, and no paging.'
servers:
- url: https://api.stophy.dev
security:
- apiKey: []
tags:
- name: Endpoints
paths:
  /v1/endpoints:
    get:
      operationId: listEndpoints
      summary: List every endpoint with its cost and input schema
      security:
      - {}
      responses:
        '200':
          description: The endpoint catalog.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointCatalog'
      tags:
      - Endpoints
components:
  schemas:
    EndpointCatalog:
      type: object
      required:
      - endpoints
      - sources
      properties:
        sources:
          type: array
          items:
            type: object
            required:
            - id
            - name
            - summary
            - kind
            properties:
              id:
                type: string
              name:
                type: string
                description: The source's name, such as YouTube or Google Maps.
              summary:
                type: string
                description: What you can get from this source.
              kind:
                type: string
                enum:
                - site
                - aiAnswers
                description: aiAnswers when the source returns another AI's answer, site otherwise.
        endpoints:
          type: array
          items:
            type: object
            required:
            - id
            - title
            - summary
            - bestWhen
            - method
            - path
            - credits
            - maxCredits
            - keyless
            - cacheTtlSeconds
            - example
            properties:
              id:
                type: string
              title:
                type: string
                description: A short name for the endpoint within its source, such as Comment replies.
              summary:
                type: string
                description: What this endpoint returns, in one line.
              bestWhen:
                type:
                - string
                - 'null'
                description: When this endpoint beats a similar one, such as another source with the same kind of data. Null when there is no overlap worth calling out.
              method:
                const: POST
              path:
                type: string
              credits:
                type: integer
                description: What one call costs, or the lowest it can cost when pricing is set.
              maxCredits:
                type: integer
                description: The most one call can cost. The same as credits when pricing is null.
              pricing:
                type:
                - string
                - 'null'
                description: How the price changes with the answer. Null when every call costs the same.
              keyless:
                type: boolean
              cacheTtlSeconds:
                type: integer
              input:
                type: object
                description: The endpoint's input as JSON Schema.
              example:
                type:
                - object
                - 'null'
                description: A real input for this endpoint, or null when there is none.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer