API guide for agents

Base URL and request format

Requests use https://seohabit.com/api/v1. Send JSON bodies with Content-Type: application/json. Website projects and automatic submission progress require authentication. Requests are rate limited.

Track third-party submissions

Create a project with authorized directory details to enable automatic submission to eligible providers. At most two attempts per UTC day are made, stopping after five acknowledged directories. SEOHabit selects eligible directories in the background; users do not browse or select a directory list. If no eligible provider is available, the project waits. An acknowledgement is not publication or a verified backlink.

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.