Update a project domain

Update an existing domain attached to a project.

This endpoint lets you update domain properties such as:

• the domain string itself

• environment (production, staging, development)

• whether it is primary

• verification/lock/payment flags

Endpoint

PUT /project/{project}/domain/{domain}

Full URL:

https://api.devpayr.dev/api/v1/project/{project}/domain/{domain}

Heads up (route naming): This endpoint uses /domain/{domain} (singular) in your route file, even though the controller annotation shows /domains/{domain}. In DevPayr, the route definition is the source of truth.

Authentication

✅ Required: API Key

Send your API key using:

X-API-KEY: <your_api_key>

Path Parameters

Parameter	Type	Required	Description
project	integer	Yes	The ID of the project.
domain	integer	Yes	The ID of the project domain record to update.

Authorization Rules

DevPayr enforces three things:

1) API key access to the project

Project-scoped keys

• If your key is scoped to a project, it must match {project}.

Error (403)

{ "message": "This API key is not allowed to access this project." }

Global keys

• If your key is global, it must belong to the owner of the project.

Error (403)

{ "message": "This API key does not have permission to access this project." }

2) Domain must belong to project

If the domain ID does not belong to the project ID, DevPayr blocks the request.

Error (404)

{ "message": "This domain does not belong to the given project." }

3) Request-level authorization message

The form request authorization throws a specific message if authorization fails:

Error (403)

{ "message": "You are not allowed to update this domain." }

Request Body

Send a JSON body containing only the fields you want to update.

All fields use sometimes, meaning:

• if present, they must be valid

• if omitted, they are not touched

Updatable Fields

Field	Type	Required	Description
domain	string	No	Must match allowed domain format. Must be unique within the same project.
environment	string	No	One of: production, staging, development.
is_primary	boolean	No	If true, DevPayr will demote any other primary domain.
is_locked	boolean	No	Lock flag.
is_verified	boolean	No	Verification flag.
has_paid	boolean	No	Payment flag (domain-level).
is_active	boolean	No	Whether the domain is active.

Boolean Input Handling

This endpoint automatically converts boolean-like values (e.g. "true", "false", 1, 0) into real booleans before validation.

Converted fields:

• is_primary

• is_locked

• is_verified

• has_paid

Domain Format Rules

If domain is provided, it must match DevPayr’s accepted formats such as:

• app.example.com

• localhost:8000

• 127.0.0.1

• [::1]:3000

Error message

{ "message": "The domain format is invalid. Examples: app.example.com, localhost:8000, 127.0.0.1, [::1]:3000." }

Uniqueness Rule

If you change the domain, it must remain unique within the same project.

Error message

{ "message": "This domain already exists in this project." }

Example Request

curl -X PUT "https://api.devpayr.dev/api/v1/project/2/domain/1" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "environment": "staging",
    "is_primary": true
  }'

Response

Success (200)

On success, DevPayr returns the updated domain record (excluding internal fields like user_id).

• message: "Domain updated successfully."

Example Response

{
    "status": "success",
    "message": "Domain updated successfully.",
    "data": {
        "id": 1,
        "project_id": 2,
        "domain": "dev.example.com",
        "environment": "staging",
        "is_primary": true,
        "is_verified": false,
        "is_locked": false,
        "last_checked_at": null,
        "has_paid": false,
        "is_active": true,
        "created_at": "2025-12-13T12:02:47.000000Z",
        "updated_at": "2025-12-13T12:10:20.000000Z"
    },
    "errors": null
}

---

Special Behavior: Setting Primary Domain

If is_primary is set to true:

• DevPayr automatically demotes every other domain where is_primary = true

• the updated domain becomes the only primary domain on that project

Caching Behavior

This endpoint caches responses per API key + project + domain + payload.

• Cache TTL: 15 minutes

• Cache key includes:

  • API key ID

  • project ID

  • domain ID

  • payload hash

If the same API key repeats the same update payload within the cache window, DevPayr may return the cached result.

Validation Errors (422)

Common validation failures:

• invalid domain format

• domain already exists in the project

• invalid environment value

Notable custom messages:

Invalid domain:

{ "message": "The domain format is invalid. Examples: app.example.com, localhost:8000, 127.0.0.1, [::1]:3000." }

Invalid environment:

{ "message": "The environment must be one of: production, staging, or development." }

Duplicate domain:

{ "message": "This domain already exists in this project." }

Errors

Missing API Key (401)

{ "message": "Missing required X-API-KEY header." }

Invalid / Expired API Key (403)

{ "message": "Invalid or expired API key." }

Unauthorized (403)

Project access failure:

{ "message": "This API key is not allowed to access this project." }

Or:

{ "message": "This API key does not have permission to access this project." }

Request authorization failure:

{ "message": "You are not allowed to update this domain." }

Domain not tied to project (404)

{ "message": "This domain does not belong to the given project." }

Project or Domain Not Found (404)

{ "message": "Resource not found." }

Rate Limited (429)

{ "message": "Rate limit exceeded (X requests/min). Please slow down." }