SubmitForBacklinks Agent API Reference

Base URL and contract

All stable agent REST endpoints are versioned under /api/v1/agent. The OpenAPI 3.1 document is the canonical schema.

Request limits

Limits are enforced across application instances. A rejected request returns HTTP 429 with an exact Retry-After value in whole seconds.

Endpoints

Authentication

Direct REST and MCP clients send the owner-scoped token in the Authorization header. The CLI obtains and stores it automatically after domain proof. Never put it in a URL or request body.

Authorization: Bearer ${SUBMITFORBACKLINKS_API_KEY}

Bounded submission lists

GET /api/v1/agent/submissions uses keyset pagination so account history remains fast as it grows. Pass limit from 1 to 100; the default is 50. When nextCursor is not null, send it unchanged as cursor on the next request. Existing clients can continue reading the submissions array and ignore the added nextCursor field.

GET /api/v1/agent/submissions?limit=50&cursor=${NEXT_CURSOR}

Durable outcomes and safe retries

Every mutating request requires a caller-generated UUID in Idempotency-Key: draft creation, direct submission, submission update, finalization, badge issue, and badge verification. The first outcome, including an error, is stored for that key. After a timeout or unknown response, reuse the same key to retrieve the exact outcome. If a replayed transient error includes error.fields.submissionId, retrieve that submission before doing anything else. Use a new UUID only after confirming that no submission exists, correcting the cause, and intentionally starting a new operation.

Idempotency-Key: 00000000-0000-4000-8000-000000000001

Direct submission requires reviewed fields

action=draft saves owner-scoped work without attestations. Domain and duplicate enforcement happens during creation, not the earlier stateless scan. action=submit is only valid when the caller has already inspected a scan result and sends all nine reviewed listing fields under overrides, plus every explicit confirmation. The server does not treat an unseen internal scan as reviewed content.

{
  "websiteUrl": "https://yourproduct.com",
  "action": "submit",
  "listingType": "FREE",
  "overrides": {
    "name": "Your Product",
    "tagline": "A focused workflow for growing SaaS teams",
    "shortDescription": "Your Product helps SaaS teams organize work and move from an idea to a clear result.",
    "fullDescription": "Your Product gives growing SaaS teams one focused workspace for planning, collaboration, and delivery. Teams can organize active work, keep decisions visible, and reduce time spent moving between disconnected tools. Review this text against the product website before submitting it.",
    "primaryCategorySlug": "productivity",
    "tags": ["Productivity", "Collaboration"],
    "pricingModel": "SUBSCRIPTION",
    "platformType": "WEB",
    "productType": "SAAS"
  },
  "attestations": {
    "guidelinesAccepted": true,
    "badgeRequirementAcknowledged": true,
    "canRepresentProduct": true,
    "reviewedGeneratedContent": true
  }
}

Correct an editable owner-scoped submission

PATCH replaces the complete set of nine listing fields on an editable owner-scoped submission. Send all nine reviewed values under overrides, even when only one changed. Founder name, contact email, and company name are optional. Updating a submitted or published working copy may return it to DRAFT for re-review while the current public listing remains live. Retrieve the submission again so the owner reviews the exact saved state before finalizing.

{
  "overrides": {
    "name": "Your Product",
    "tagline": "A focused workflow for growing SaaS teams",
    "shortDescription": "Your Product helps SaaS teams organize work and move from an idea to a clear result.",
    "fullDescription": "Your Product gives growing SaaS teams one focused workspace for planning, collaboration, and delivery. Teams can organize active work, keep decisions visible, and reduce time spent moving between disconnected tools.",
    "primaryCategorySlug": "productivity",
    "tags": ["Productivity", "Collaboration"],
    "pricingModel": "SUBSCRIPTION",
    "platformType": "WEB",
    "productType": "SAAS"
  },
  "founderName": "Founder Name",
  "contactEmail": "[email protected]",
  "companyName": "Your Company"
}

Finalize an existing draft

Retrieve and review the saved draft first, then use its submission ID. The finalization request independently requires an idempotency key and all four confirmations. launchWeekStart is optional; the service otherwise selects the next available week.

{
  "attestations": {
    "guidelinesAccepted": true,
    "badgeRequirementAcknowledged": true,
    "canRepresentProduct": true,
    "reviewedGeneratedContent": true
  }
}

Issue, install, and verify the free-listing badge

POST action=issue to receive the exact badge markup, install one returned theme on a public HTTPS page of the submitted domain, then POST its targetUrl to the verification endpoint. GET the badge resource to inspect status, failure reason, timestamps, follow-window state, link policy, and markup. Verification completed before publication remains pending until the approved listing goes live.

{
  "action": "issue"
}

{
  "targetUrl": "https://yourproduct.com/partners"
}

Optional media is dashboard-managed

A logo and up to three screenshots are optional listing media. Agent API v1 has no media-upload operation; REST, CLI, and MCP clients cannot upload or replace these files.

Stable error envelope

Branch on error.code. Display error.message to the operator, use fields for validation, and respect the Retry-After header on HTTP 429 instead of retrying immediately.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Review the highlighted fields.",
    "fields": {
      "launchWeekStart": ["Choose an available free launch week."]
    }
  }
}