API guide for agents

Base URL and request format

Requests use https://seohabit.com/api/v1. Send JSON bodies with Content-Type: application/json. Public directory lookup, submissions, and anonymous backlink checks do not require an account. Requests are rate limited.

Find directory suggestions

Directory data is a suggestion list and match assessment. Check each directory’s current official rules before acting.

curl 'https://seohabit.com/api/v1/directories?category=ai&pricing=free&q=launch'

Supported categories are saas, ai, developer, pdf, productivity, and startup. Pricing is free, freemium, or paid; it defaults to free. Results include matched, needs_review, or not_eligible with a reason.

Submit a product

A submission enters validation and editorial review. It is not an automatic directory submission or a promise of publication. The API accepts public HTTP(S) website URLs on standard ports; local and private network addresses are rejected.

curl -X POST 'https://seohabit.com/api/v1/submissions' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 3e41e737f67c4d8abfda0f15' \
  -d '{"website":"https://example.com/","name":"Example","description":"A product description with at least forty characters for review.","category":"ai","pricing":"freemium"}'

Save the returned accessToken securely. It is shown once and authorizes reading this submission receipt. Send it in X-Access-Token; do not put it in a URL, query string, or log. Repeating the same request with the same idempotency key and body returns the stored response. Reusing that key with a different body returns 409.

curl 'https://seohabit.com/api/v1/submissions/sub_example' \
  -H 'X-Access-Token: YOUR_SUBMISSION_ACCESS_TOKEN'

Check an external link

Anonymous checks inspect a public source page for a link to the target URL. The check is asynchronous and does not prove that a listing was approved, indexed, or followed by a search engine.

curl -X POST 'https://seohabit.com/api/v1/backlink-checks' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 81b47a1df6274d88956f3931' \
  -d '{"sourceUrl":"https://directory.example/listing/example","targetUrl":"https://example.com/","matchMode":"exact"}'

matchMode may be exact or domain; it defaults to exact. The response contains a job ID, status URL, and one-time access token.

Poll a job

Poll the status URL until the job reaches completed or failed. Authenticate every poll with the job’s access token in the header. A job token only grants access to its own job.

curl 'https://seohabit.com/api/v1/jobs/job_example' \
  -H 'X-Access-Token: YOUR_JOB_ACCESS_TOKEN'

Responses include queued, running, completed, or failed; result is null until available.

Accounts, project keys, and paid actions

Account registration and login set an HttpOnly sh_session cookie. Browser cookie writes are origin checked. For integrations, a signed-in account can create a project-scoped API key with explicit scopes and send it as Authorization: Bearer shk_…. Keys cannot access another project, and key scopes limit available operations. Keep session cookies and API keys secret; never include them in URLs.

Keyword tasks accept details.keyword, optional details.language (default en) and an optional explicit details.pageUrl. Suggestions expose matching page evidence and mark unknown language or search demand.

Website audits can be queued on a free project at the free allowance. Monitored backlinks, task creation, and task execution require a verified website and an active subscription. A paid action requires a person to establish ownership and explicitly obtain the subscription through the account billing flow. Do not start checkout, subscribe, or authorize changes to a website on someone’s behalf. Task execution is not evidence that a change was applied; a ready task requires user review and acceptance.

Project keys support project:read, project:write, checks:write, and tasks:write. A key only applies to its own project. See the OpenAPI document for routes and request shapes.

Errors and safe use

Errors use JSON with error and message. Common responses include 400 for invalid input or unsafe URLs, 401 for missing account authentication, 403 for a disallowed origin or scope, 404 for unavailable resources, 409 for conflicts, 429 for rate limits, and 402 when a paid action requires an active subscription.

Only check public pages you are authorized to inspect. The service blocks private and local network destinations and follows the source site’s crawler policy where available. Use idempotency keys for retryable POST requests and handle rate-limit responses with backoff.