AgentsIndex Submit API

openapi: 3.2.0
info:
  title: AgentsIndex — machine Submit API
  version: 1.0.0
  description: 'AgentsIndex is the reference index of AI-native tools: an ongoing, edited catalog of AI agents, AI-first products, and the tools that power them. Free, keyless read endpoints over the tools corpus, plus verified-session submission intake. AgentsIndex reuse terms (https://agentsindex.ai/terms): Search engines, AI assistants answering a question and AI models in training may all read and reuse these listings. Say the facts came from AgentsIndex and link the listing you used.'
  license:
    name: AgentsIndex reuse terms
    url: https://agentsindex.ai/terms
servers:
- url: https://agentsindex.ai
tags:
- name: Submit
paths:
  /api/submit:
    post:
      operationId: submitListing
      summary: Submit a tool (verified account session; Draft pending review)
      description: 'Requires an existing signed-in account with verified email. Sign in or create an account explicitly at https://agentsindex.ai/login?next=%2Fsubmit, verify its email, then send its session cookie. Identity and email come only from that session; submission never creates an account or sends verification email. Missing session returns 401 sign_in_required with an actionable loginUrl; unverified email returns 403 email_unverified with email and remediation. Neither refusal stores a listing or sends mail. Submissions come from the company itself: the account''s address, or an address it proved with a code through /api/domain-proof/start and /api/domain-proof/verify, must be on the website''s domain; otherwise the answer is 403 domain_unverified with the domain and remediation. A code to an address at the domain is the only proof. A research pass + quality gate decide publication; the Draft cannot inject page copy or self-publish. The fit check starts at once and usually answers within a minute: poll GET https://agentsindex.ai/api/submissions/{id} and wait the Retry-After seconds it sends while fit is "checking". fit then reads "accepted" (it goes live, and the account is mailed), "rejected" (mailed with the reason) or "undecided" (a person looks within 2 days). Authentication and verification precede idempotency: your own (url, session email) replay within 24h returns the existing draft (200). An Idempotency-Key header is accepted; the effective dedupe key is (url, session email).'
      security:
      - sessionCookie: []
      - agentKey: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: Accepted for convention; own replay dedupe is by (url, session email) within 24h regardless.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitInput'
      responses:
        '200':
          description: Deduplicated — your existing draft for this (url, session email).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionStatus'
        '201':
          description: Draft created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionStatus'
        '400':
          description: Validation failed (bad url/name).
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Sign in or create an account explicitly at loginUrl, then verify email and retry. No account, mail or listing created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignInRequired'
        '403':
          description: 'email_unverified: verify the session account email and retry. domain_unverified: prove an address at the returned domain with a code through /api/domain-proof/start and /verify, then retry. Submitting for someone else, with no mailbox at the domain? Give the owner ownerUrl, the submit page with the site filled in: they prove it there with a code, or skip the proof as `skip` says. No listing or mail created.'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/EmailUnverified'
                - $ref: '#/components/schemas/DomainUnverified'
        '409':
          description: 'Already listed / duplicate, or free_limit: the account has its free listings (one a day, two in all).'
          content:
            application/json:
              schema:
                type: object
      tags:
      - Submit
components:
  schemas:
    SubmissionStatus:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        status:
          type: string
          enum:
          - Draft
          - Processing
          - Review
          - Published
          - Rejected
        submittedAt:
          type: string
          format: date-time
        fit:
          type: string
          enum:
          - checking
          - accepted
          - rejected
          - undecided
          description: Where the fit check stands. It runs right after submission and usually answers within a minute; undecided means a person decides it within 2 days.
    EmailUnverified:
      type: object
      required:
      - error
      - message
      - email
      - remediation
      properties:
        error:
          type: string
          const: email_unverified
        message:
          type: string
        email:
          type: string
          format: email
        remediation:
          type: string
    DomainUnverified:
      type: object
      required:
      - error
      - message
      - domain
      - remediation
      - ownerUrl
      - skip
      properties:
        error:
          type: string
          const: domain_unverified
        message:
          type: string
        domain:
          type: string
          description: The host the account has not yet proven.
        remediation:
          type: string
        ownerUrl:
          type: string
          format: uri
          description: The submit page with this website filled in (/submit?url=…), for an agent to hand to the human owner, who proves the site there with a code to their own mailbox or skips the proof.
        skip:
          type: string
          description: 'The page''s "Skip for now" in one line: any email address, listed free below listings with verified owners and on a later day, provable any time after.'
    SignInRequired:
      type: object
      required:
      - error
      - message
      - loginUrl
      properties:
        error:
          type: string
          const: sign_in_required
        message:
          type: string
        loginUrl:
          type: string
          format: uri
          examples:
          - https://agentsindex.ai/login?next=%2Fsubmit
    SubmitInput:
      type: object
      required:
      - url
      description: 'The website alone: we write its name and one-line description from its own pages.'
      properties:
        url:
          type: string
          description: The website being submitted (https).
  securitySchemes:
    agentKey:
      type: http
      scheme: bearer
      description: An agent key the account made at https://agentsindex.ai/dashboard/agents (it starts with mak_). It acts as that account on submit, the claim and domain-proof steps, quotes, orders and reading its own listings, each by the scope the key was given, with the same refusals as its session; it cannot sign in, change the account or pay.
    sessionCookie:
      type: apiKey
      in: cookie
      name: __Secure-better-auth.session_token
      description: Existing Better Auth session cookie issued through https://agentsindex.ai/login?next=%2Fsubmit. The account email must be verified for submission. This is a session cookie, not an API key to provision.