Device sign-in

• 201

  The sign-in is waiting for approval.

  Field	Type	Notes
  device_code*	string	Opaque. Keep it private and send it when you poll.
  user_code*	string	What the person confirms on the approval screen.
  verification_uri*	uri
  verification_uri_complete*	uri	The approval page with the code filled in. Show this one when you can.
  expires_in*	1800
  interval*	5	Seconds to wait between polls.

• 400

  INVALID_REQUEST. The request could not be parsed, or a parameter is not usable: bad JSON, an unknown query parameter value, or a missing required header.

• 409

  SLUG_CONFLICT, IDEMPOTENCY_KEY_CONFLICT, IDEMPOTENCY_KEY_IN_FLIGHT or CONFLICT. The request is valid but collides with the current state: a slug is taken, an idempotency key was reused with a different body or is still in flight, or the object moved while you were working on it. Read code to tell which, then re-read and retry.

• 422

  VALIDATION_FAILED. The request parsed but the values are not acceptable. error.fields maps each offending field to a message you can put next to the input.

  Common causes: publishing without a title, slug or content; scheduling in the past; and sending status on a create or update, which is how the API refuses to let a client push content into the AI pipeline.

• 429

  RATE_LIMIT_EXCEEDED. Back off and honour Retry-After.

  Limits are per key, per minute, by endpoint class. Writes are limited harder than reads because they cost more to serve, and pipeline runs hardest of all because they cost real money. The two device sign-in endpoints take no key, so they are limited per IP address instead.

  Class	Endpoints	Limit
  read	every GET	600 per minute
  write	POST, PATCH and DELETE on content, taxonomy, keys and webhooks	120 per minute
  upload	POST /media/upload-url	60 per minute
  pipeline	POST /pipeline/runs	10 per minute
  auth	POST /auth/device and POST /auth/device/token, per IP address	60 per minute

  Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, so you can slow down before you are refused rather than after.

  • RateLimit-Limit Requests permitted in the current window for this endpoint class.
  • RateLimit-Remaining Requests left in the current window.
  • RateLimit-Reset Unix seconds at which the window resets.
  • Retry-After Seconds to wait before retrying.
• 500

  INTERNAL_ERROR. Something failed on our side. The message is deliberately generic; the detail is in our logs against the request_id in the body, so quote it if you contact support.

  Safe to retry, and safer still with the same Idempotency-Key, which guarantees you do not create a second object if the first request actually succeeded.

• 503

  MAINTENANCE. Writes are paused, either platform wide or for your Site. Reads usually keep working, and your published blog is served from cache and stays up. Retry after the window given in Retry-After.

  • Retry-After Seconds to wait before retrying.

curl -X POST https://api.writavo.com/v1/auth/device \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
  "client_name": "<client_name>",
  "key_hash": "<key_hash>",
  "key_prefix": "<key_prefix>",
  "scopes": "<scopes>"
}'

Generated from the specification, so it shows the path, the required headers and the body shape. The guides carry the end to end examples.

• 200

  The current outcome.

  Field	Type	Notes
  status*	string	one of pending, slow_down, approved, denied, expired
  interval	integer	Present on slow_down. Seconds to wait before polling again.
  key	object	Present on approved.
  website	object	Present on approved. The Site the key belongs to.

• 400

  INVALID_REQUEST. The request could not be parsed, or a parameter is not usable: bad JSON, an unknown query parameter value, or a missing required header.

• 404

  NOT_FOUND. Either no such object exists, or it exists and belongs to a different Site.

  These two cases are deliberately indistinguishable, and neither ever returns 403. A 403 would confirm the object exists, which would let anyone with a valid key enumerate other customers' content by id. If you are certain the id is right, check you are using the key for the correct Site.

• 422

  VALIDATION_FAILED. The request parsed but the values are not acceptable. error.fields maps each offending field to a message you can put next to the input.

  Common causes: publishing without a title, slug or content; scheduling in the past; and sending status on a create or update, which is how the API refuses to let a client push content into the AI pipeline.

• 429

  RATE_LIMIT_EXCEEDED. Back off and honour Retry-After.

  Limits are per key, per minute, by endpoint class. Writes are limited harder than reads because they cost more to serve, and pipeline runs hardest of all because they cost real money. The two device sign-in endpoints take no key, so they are limited per IP address instead.

  Class	Endpoints	Limit
  read	every GET	600 per minute
  write	POST, PATCH and DELETE on content, taxonomy, keys and webhooks	120 per minute
  upload	POST /media/upload-url	60 per minute
  pipeline	POST /pipeline/runs	10 per minute
  auth	POST /auth/device and POST /auth/device/token, per IP address	60 per minute

  Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, so you can slow down before you are refused rather than after.

  • RateLimit-Limit Requests permitted in the current window for this endpoint class.
  • RateLimit-Remaining Requests left in the current window.
  • RateLimit-Reset Unix seconds at which the window resets.
  • Retry-After Seconds to wait before retrying.
• 500

  INTERNAL_ERROR. Something failed on our side. The message is deliberately generic; the detail is in our logs against the request_id in the body, so quote it if you contact support.

  Safe to retry, and safer still with the same Idempotency-Key, which guarantees you do not create a second object if the first request actually succeeded.

• 503

  MAINTENANCE. Writes are paused, either platform wide or for your Site. Reads usually keep working, and your published blog is served from cache and stays up. Retry after the window given in Retry-After.

  • Retry-After Seconds to wait before retrying.

curl -X POST https://api.writavo.com/v1/auth/device/token \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
  "device_code": "<device_code>"
}'

Generated from the specification, so it shows the path, the required headers and the body shape. The guides carry the end to end examples.