Create single URL

POST

/api/v1/urls

curl -X POST 'https://dashboard.justcrawl.io/api/v1/urls' \
  -H 'Authorization: Bearer $JUSTCRAWL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/products/123","priority":10}'

• Production

Adds a single URL to the org’s URL list. The URL is validated for syntax and private-address blocking (RFC 1918 / loopback hosts are rejected to prevent SSRF). Duplicate URLs within the same org return 409 — re-submitting an existing URL is a no-op, not a way to refresh scheduling. Use POST /api/v1/urls/batch for >1 URL at a time; this single-URL endpoint exists for dashboard-driven adds and quick API smoke tests.

Authorizations

• bearerAuth

Request Body ^required

Media type application/json

object

url

required

Absolute URL with scheme (http:// or https://).

string

priority

Optional dispatch priority; higher values dispatch first when capacity is constrained.

integer

tags

Optional list of tag slugs to attach. Use the same charset rules as POST /api/v1/urls/{id}/tags.

Array<string>

Example ^generated

{
  "url": "example",
  "priority": 1,
  "tags": [
    "example"
  ]
}

Responses

201

Created URL item.

Media type application/json

object

id

string format: uuid

url

string

domain

string

priority

integer

tags

Array<string>

createdAt

string format: date-time

Example ^generated

{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "url": "example",
  "domain": "example",
  "priority": 1,
  "tags": [
    "example"
  ],
  "createdAt": "2026-04-15T12:00:00Z"
}

400

Validation failed — request body or query is missing/invalid

Media type application/json

object

error

string

Example

{
  "error": "Missing or invalid \"url\" field"
}

401

Missing or invalid authentication token

Media type application/json

object

error

string

Example

{
  "error": "Missing or invalid authentication token"
}

403

Insufficient permissions for this operation

Media type application/json

object

error

string

Example

{
  "error": "No organization. Complete onboarding first."
}

409

Operation conflicts with current resource state

Media type application/json

object

error

string

Example

{
  "error": "Resource already exists"
}

500

Unexpected server error. Logs and PostHog $exception capture

Media type application/json

object

error

string

Example

{
  "error": "Something went wrong"
}