CitedIndex Submit API

openapi: 3.2.0
info:
  title: CitedIndex — machine Submit API
  version: 1.0.0
  description: 'The neutral index of AI-visibility and GEO tools: which ones track whether ChatGPT, Perplexity, Gemini and AI Overviews cite your brand. Researched and compared. Free, keyless read endpoints over the tools corpus, plus verified-session submission intake. CitedIndex Data Terms (https://citedindex.com/terms): Search engines and AI assistants may read CitedIndex and quote it in their answers, and AI models may be trained on it. Credit CitedIndex and link to https://citedindex.com when you quote it.'
  license:
    name: CitedIndex Data Terms
    url: https://citedindex.com/terms
servers:
- url: https://citedindex.com
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://citedindex.com/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. The product''s owner proves it before anything is listed, whoever submits: otherwise the answer is 403 domain_unverified with status awaiting_owner_proof and listed false, naming who can receive the code (proveWith) and the page where the owner enters it (ownerUrl). Nothing is listed or queued until then. A code to an address at the domain is the proof; a project on GitHub or another shared host proves its listed addresses or a one-line file. 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://citedindex.com/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 (status awaiting_owner_proof, listed false): the owner must prove the site first. With a mailbox at the domain, prove it with a code through /api/domain-proof/start and /verify, then retry. Submitting for someone else? Give the owner ownerUrl, the submit page with the site filled in, where they enter the code; the listing goes in once proven. 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:
    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
    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).
    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.
    DomainUnverified:
      type: object
      required:
      - error
      - status
      - listed
      - message
      - domain
      - proveWith
      - ownerUrl
      - ownerStep
      - remediation
      properties:
        error:
          type: string
          const: domain_unverified
        status:
          type: string
          const: awaiting_owner_proof
          description: 'Waiting on the owner: nothing is listed or queued until they prove the site.'
        listed:
          type: boolean
          const: false
        message:
          type: string
        domain:
          type: string
          description: The host the account has not yet proven.
        proveWith:
          type: string
          description: 'Who can receive the 6-digit code: any address at the domain, or for a project on a shared host such as GitHub, its listed addresses or a one-line file (POST /api/domain-proof/place lists which).'
        ownerUrl:
          type: string
          format: uri
          description: The submit page with this website filled in (/submit?url=…), for an agent to hand to the owner, who asks for the code and enters it there.
        ownerStep:
          type: string
          description: The owner's next step in one line, to relay as it is.
        remediation:
          type: string
    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://citedindex.com/login?next=%2Fsubmit
  securitySchemes:
    agentKey:
      type: http
      scheme: bearer
      description: An agent key the account made at https://citedindex.com/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://citedindex.com/login?next=%2Fsubmit. The account email must be verified for submission. This is a session cookie, not an API key to provision.