PATCH/v1/drafts/{draft_id}

Actualizar un borrador

update_draft

Todos los campos son opcionales. scheduled_publish_at: null cancela la publicación programada. Editar un borrador aprobado lo devuelve a publish_requested. Una clave de API puede editar un borrador en las mismas condiciones en que lo lee (desde 1.62.0).

Autenticación

Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.

Parámetros de ruta

draft_idintegerobligatorio

Parámetros de encabezado

Idempotency-Keystring
Clave para reintentar de forma segura una escritura: de 1 a 255 caracteres ASCII imprimibles; se recomienda un UUID v4 por operación lógica. Un reintento con la misma clave en un plazo de 24 horas no vuelve a ejecutar la operación: devuelve la respuesta guardada (estado, encabezados y cuerpo) con el encabezado Idempotency-Replayed: true. La misma clave con otro método, otra ruta, otro Content-Type u otro cuerpo devuelve 409 api.idempotency_mismatch; mientras la primera solicitud sigue en curso, 409 api.idempotency_in_progress con Retry-After: 1. Tras una respuesta 5xx o 429, la clave se libera y un reintento vuelve a ejecutar la operación. La clave se aplica a la organización y a quien llama a la API (clave de API, usuario o clave de fuente personalizada).
length ≥ 1, length ≤ 255

Cuerpo de la solicitud

application/json

Objeto: DraftUpdate

titlestring | null
length ≤ 200
body_markdownstring | null
length ≤ 500000
tagsarray of string | null
items ≤ 30
revision_notestring | null
length ≤ 1000
verify_on_publishboolean | null
notify_followersboolean | null
scheduled_publish_atstring (date-time) | null
null cancela la publicación programada; un campo que no está en el cuerpo no cambia.

Respuestas

200Respuesta correcta

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.
Idempotency-Replayed
true significa que la respuesta se reprodujo a partir de la guardada para esta Idempotency-Key: la operación no se volvió a ejecutar.

application/json

Objeto: Draft

idintegerobligatorio
org_idintegerobligatorio
card_idstring | nullobligatorio
La tarjeta que edita el borrador; null: un borrador de una tarjeta nueva.
collection_idintegerobligatorio
collectionstringobligatorio
titlestringobligatorio
body_markdownstringobligatorio
tagsarray of stringobligatorio
base_versioninteger | null
Versión de la tarjeta a partir de la cual se empezó el borrador.
scheduled_publish_atstring (date-time) | null
workflow_stateDraftWorkflowStateobligatorio
revision_notestring | null
verify_on_publishbooleanobligatorio
notify_followersbooleanobligatorio
created_byintegerobligatorio
updated_byinteger | null
created_atstring (date-time)obligatorio
updated_atstring (date-time)obligatorio
publish_requested_byinteger | null
publish_requested_atstring (date-time) | null
approved_byinteger | null
approved_atstring (date-time) | null
collaboratorsarray of DraftCollaboratorobligatorio
conflictstring | null
card_published: la tarjeta se publicó o cambió después de empezar el borrador; card_deleted: la tarjeta se eliminó; ampliable.

400La solicitud no es válida: el valor de un parámetro o el estado del objeto no permiten la acción (`detail` es un mensaje).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

401No se enviaron credenciales (ni una cookie de sesión ni una clave de API) o no se encontró la clave.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

403La acción no está permitida: el rol no es suficiente, no hay acceso a la colección o a la tarjeta, la solicitud se ejecuta en modo «View as», o la organización está suspendida o eliminada (`detail` es un objeto con `code: org_suspended | org_deleted`).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

404El objeto no existe o no está disponible para usted. La API no confirma la existencia de un objeto restringido.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

409El estado del objeto no permite la acción, por ejemplo, un duplicado, una indexación en curso o un trabajo ya procesado.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

422Error de validación: el cuerpo o los parámetros no coinciden con el esquema (`detail` es una lista de errores de validación), o el valor de un parámetro está fuera del rango permitido (`detail` es un mensaje).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

429Demasiadas solicitudes (`api.rate_limited`), se agotó la cuota de la organización para el minuto, el día o el mes (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` y `reset_at`), se alcanzó el límite de la organización o el servicio de respuestas está ocupado (`answers.engine_busy`). Espere el tiempo indicado en el encabezado `Retry-After`.

Encabezados de la respuesta

Retry-After
Número de segundos que hay que esperar antes de reintentar la solicitud.
RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

Códigos de error

Códigos que este endpoint puede devolver en error.code, además de los códigos generales de cualquier solicitud.

Reintentos seguros

Envíe un encabezado Idempotency-Key (por ejemplo, un UUID) con cada POST y PATCH. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta guardada en lugar de volver a ejecutar la solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← drafts · Referencia de la API

curl -X PATCH 'https://api.sursa.com/v1/drafts/1' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund policy","body_markdown":"# Refund policy\n\nRefunds are processed within 14 days.","tags":["string"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Probar

Clave de API

La clave se queda en la memoria de esta pestaña y solo se envía a https://api.sursa.com.

Las solicitudes actúan sobre los datos reales de su organización.

Idempotency-Key header

draft_id path *

Idempotency-Key

Si este campo está vacío, se genera una clave nueva para cada solicitud.

Cuerpo de la solicitud (JSON)