reference

Meta

Connectivity, Site information, content types, limits and usage.

GET/ping

Verify a key#

Scope: none
Rate limit: 600/min (read)
Publishable key: allowed
Dashboard permission: none

The cheapest possible authenticated call. Returns the kind of key you presented and the scopes it carries. Use it to confirm credentials during setup, and as a liveness probe. It touches no content, so it is exempt from the write rate limit.

Responses

200

The key is valid.

Field	Type	Notes
pong*	true
key_kind*	KeyKind	`publishable` keys are prefixed `wv_pub_` and are safe in client code: read only, limited to published content, and admitted only to the operations marked `x-publishable: true`. Anything else returns `403 INSUFFICIENT_SCOPE`, whatever scopes the key carries. `secret` keys are prefixed `wv_sk_` and are server side only.
scopes*	Scope

401
INVALID_API_KEY, API_KEY_REVOKED or API_KEY_EXPIRED. There is no key, or it is not usable. This response never distinguishes "no such key" from "wrong key", so a caller cannot probe for valid keys.

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.

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

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.

Request shape

curl

curl https://api.writavo.com/v1/ping \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000"

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

GET/site

Read Site information#

Scope: meta:read
Rate limit: 600/min (read)
Publishable key: allowed
Dashboard permission: none

Public facing information about the Site your key belongs to: its display name, the domain its blog is served from, its locale and its timezone. Scheduling times are interpreted against this timezone when no offset is supplied.

Responses

200Site
Site information.
401
INVALID_API_KEY, API_KEY_REVOKED or API_KEY_EXPIRED. There is no key, or it is not usable. This response never distinguishes "no such key" from "wrong key", so a caller cannot probe for valid keys.
403
INSUFFICIENT_SCOPE. The key is valid but does not carry the scope this operation requires, or its creator's permissions no longer cover it.
This is the only 403 in the API. In particular it is never returned for an object belonging to another Site: that case is always 404, so this response never reveals that something exists.

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.

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

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.

Request shape

curl

curl https://api.writavo.com/v1/site \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000"

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

GET/content-types

List content types#

Scope: meta:read
Rate limit: 600/min (read)
Publishable key: allowed
Dashboard permission: none

The article formats available to this Site. A format is an SEO blueprint (How-To, Listicle, Versus and so on) that shapes how the generator structures an article, and that you may set on any article via format_id.

The list merges the platform defaults with any formats defined for your Site. A Site format with the same key as a platform default overrides it, and only the override is returned. Formats are read only in v1: defining your own is a dashboard action.

Responses

200ContentType
The available content types.
Field Type Notes
items* ContentType
401
INVALID_API_KEY, API_KEY_REVOKED or API_KEY_EXPIRED. There is no key, or it is not usable. This response never distinguishes "no such key" from "wrong key", so a caller cannot probe for valid keys.
403
INSUFFICIENT_SCOPE. The key is valid but does not carry the scope this operation requires, or its creator's permissions no longer cover it.
This is the only 403 in the API. In particular it is never returned for an object belonging to another Site: that case is always 404, so this response never reveals that something exists.

Field	Type	Notes
items*	ContentType

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.

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

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.

Request shape

curl

curl https://api.writavo.com/v1/content-types \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000"

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

GET/usage

Read plan limits, usage and balances#

Scope: meta:read
Rate limit: 600/min (read)
Publishable key: refused
Dashboard permission: none

What your plan allows, what you have used in the current period, and what you can still spend. Read this before a pipeline run if you want to fail fast rather than handle a 402, and read it after a run to see the balance move.

credits.balance is the organisation wide credit balance shared by every Site under the account. spend_cap is this Site's own monthly ceiling and is independent of it: a Site can be capped while the organisation still has credits, which is the point of a cap.

Responses

200Usage
Limits, usage and balances.
401
INVALID_API_KEY, API_KEY_REVOKED or API_KEY_EXPIRED. There is no key, or it is not usable. This response never distinguishes "no such key" from "wrong key", so a caller cannot probe for valid keys.
403
INSUFFICIENT_SCOPE. The key is valid but does not carry the scope this operation requires, or its creator's permissions no longer cover it.
This is the only 403 in the API. In particular it is never returned for an object belonging to another Site: that case is always 404, so this response never reveals that something exists.

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.

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

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.

Request shape

curl

curl https://api.writavo.com/v1/usage \
  -H "Authorization: Bearer wv_sk_EXAMPLE0000000000000000000000000000"

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

Schemas

The shapes this resource sends and returns. Unknown fields may be added within /v1, so tolerate them.

ContentType#

An article format, that is, an SEO blueprint you can set on an article via format_id.

Field	Type	Notes
id*	uuidread only
key*	string
name*	string
is_active	boolean
is_platform_default	boolean	True for a format we ship, false for one defined on your Site.

KeyKind#

publishable keys are prefixed wv_pub_ and are safe in client code: read only, limited to published content, and admitted only to the operations marked x-publishable: true. Anything else returns 403 INSUFFICIENT_SCOPE, whatever scopes the key carries.

secret keys are prefixed wv_sk_ and are server side only.

publishablesecret

Scope#

What a key is permitted to do. A key carries a set of these, and every operation names the one it needs.

Scope is the outer bound, not the whole answer. A request must also pass the creator's live permissions, the plan entitlement, and, for a pipeline run, credits and the spend cap. A scope you hold can still be refused by the gate behind it.

A publishable key may only carry :read scopes, and only ever sees published content. Three of them are deliberately NOT available to a publishable key, because the endpoints behind them return things a browser bundle must not carry: media:read lists the whole library including assets attached only to drafts, pipeline:read returns the Site's unpublished editorial queue, and webhooks:read is account configuration.

meta:read IS publishable, but GET /usage within it is not: it returns the organisation's credit balance and plan, and a publishable key presenting it gets 403 INSUFFICIENT_SCOPE. Every operation states which side of that line it is on in x-publishable.

articles:readarticles:writetaxonomy:readtaxonomy:writeauthors:readauthors:writemedia:readmedia:writepipeline:readpipeline:runkeys:readkeys:writewebhooks:readwebhooks:writemeta:read

Site#

Field	Type	Notes
id*	uuidread only	The identifier of the Site this key belongs to, for your own logging and support requests. It is never a request parameter: the Site is always resolved from the key, so sending it anywhere would have no effect.
name*	string
domain	string \| null	The domain the blog is served from, if a delivery route is configured.
blog_base_url	uri \| null	The base URL published articles appear under.
locale	string \| null
timezone	string \| null	IANA name. Scheduling timestamps without an offset are read in this zone.
pipeline_enabled	boolean	Whether the AI engine runs on its own cadence for this Site. False means the CMS works exactly as before and nothing is generated unless you ask for a run.

Usage#

Plan limits, current period usage, credit balance and spend cap in one payload. Read it before a pipeline run to fail fast, or after one to see the balance move.

Field	Type	Notes
plan*	object
period*	object
limits*	object[]	One row per metered limit, with what you have used against it.
features	string[]	Capability keys your plan grants. A pipeline run needs `ai.article_generation`.
credits*	object
spend_cap	object	This Site's own monthly ceiling, independent of the organisation balance.