Skip to content
calternal docs

Add a block reminder

POST
/api/v1/notes/{id}/reminders
curl --request POST \
  --url https://example.com/api/v1/notes/example/reminders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: example' \
  --data '{ "audience": "everyone", "block_id": "example", "instant": "example" }'

Requires a signed-in User with the data scope and edit access to the Note. It returns 400 for an invalid block or time, 404 when the Note is missing, 409 when reminder data is invalid, 412 when the Note changed, or 428 when If-Match is missing. Route: /api/v1/notes/{id}/reminders. Inputs: id, If-Match. Do not automatically replay this operation after an uncertain result.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Header Parameters

Section titled “Header Parameters”
If-Match
required
string

Current Note ETag

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
audience

Users who can see the Note at fire time, or only the setter.

string
Allowed values: everyone only_me
block_id
required

Existing stable Markdown block anchor (^id).

string
instant
required

One absolute instant in RFC 3339 form.

string

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
audience
required

everyone or only_me.

string
block_id
required

Stable block identity within the Note.

string
id
required

Stable UUID key in calternal-reminders.

string
instant
required

Absolute trigger time, normalized to UTC.

string
revision
required

Monotonic reminder revision used to fence a stale Undo.

integer format: int64
setter
required

User who set this reminder.

string
Examplegenerated
{
  "audience": "example",
  "block_id": "example",
  "id": "example",
  "instant": "example",
  "revision": 1,
  "setter": "example"
}

400

Section titled “400”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

401

Section titled “401”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

404

Section titled “404”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

409

Section titled “409”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

412

Section titled “412”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}

422

Section titled “422”

The JSON request body does not match the declared request schema

Media typetext/plain
string

428

Section titled “428”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}