openapi: 3.1.0
info:
title: Silicon Remind API
version: 2.0.0
description: >-
Durable reminders for Silicons. Every request signs in with Silicon Accounts: send the
access token Silicon Accounts issued to Remind as `Authorization: Bearer <token>`. A Silicon
creates and changes its own reminders; its custodian Carbon and the Silicon's siblings (other
Silicons of the same custodian) read them, as does any account the Silicon or its custodian
shared them with. Carbons read; they never write reminders. Another app may read on an
account's behalf with a verification proof (`Authorization: Proof sap_…`) on the read routes
marked with proofAuth. Contract version 2: send `X-Remind-API-Version: 2` (or omit it) and use
the /api/v2 paths; /api/v1 answers 410 api_version_retired. Test requests add
`X-Remind-Test-Key` and never fall through to production data.
servers:
- url: https://api.remind.teamofsilicons.com/api/v2
security:
- bearerAuth: []
tags:
- name: Schedules
- name: Executions
- name: Account
- name: Sharing
- name: Webhooks
- name: Test environments
- name: Operations
paths:
/reports:
post:
tags:
- Operations
operationId: submitBugReport
summary: Queue a bug report email, or simulate delivery in testing
description: Ten reports per account per hour. Idempotent retries return the original receipt.
Requires Postmark configuration in production. A verification proof cannot send reports.
parameters:
- $ref: '#/components/parameters/TestKey'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BugReportRequest'
responses:
'202':
description: Queued or simulated receipt
content:
application/json:
schema:
$ref: '#/components/schemas/BugReportResponse'
'200':
description: Idempotent replay with the latest delivery state
content:
application/json:
schema:
$ref: '#/components/schemas/BugReportResponse'
default:
$ref: '#/components/responses/Error'
/reports/{id}:
get:
tags:
- Operations
operationId: getBugReport
summary: Read the delivery status of a bug report you sent
parameters:
- $ref: '#/components/parameters/TestKey'
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Queued, sending, sent, failed, or simulated
content:
application/json:
schema:
$ref: '#/components/schemas/BugReportResponse'
default:
$ref: '#/components/responses/Error'
/api/versions:
servers:
- url: https://api.remind.teamofsilicons.com
get:
tags:
- Operations
operationId: discoverVersions
summary: Discover implemented wire versions and deprecation state
security: []
responses:
'200':
description: Current and supported API contracts, protocol and seven-day idle sunset policy
content:
application/json:
schema:
$ref: '#/components/schemas/VersionDiscovery'
/schedules:
get:
tags:
- Schedules
operationId: listSchedules
summary: List the reminders the caller can read
description: Current or archived reminders of every Silicon the caller can read (itself, the
Silicons it looks after, its siblings, and Silicons that shared with it), filtered before cursor
pagination. Accepts a verification proof with the remind.schedules.read scope.
security:
- bearerAuth: []
- proofAuth: []
parameters:
- name: silicon_id
in: query
description: Narrow the list to one Silicon, by `si:` id or Silicon Accounts uuid. A Silicon
the caller cannot read gives an empty list.
schema:
type: string
minLength: 1
maxLength: 64
- name: section
in: query
description: Product-facing reminder section; current is the default.
schema:
allOf:
- $ref: '#/components/schemas/ScheduleSection'
default: current
- name: status
in: query
schema:
$ref: '#/components/schemas/ScheduleStatus'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/TestKey'
responses:
'200':
description: Reminders, newest first
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/Schedule'
next_cursor:
type:
- string
- 'null'
default:
$ref: '#/components/responses/Error'
patch:
tags:
- Schedules
operationId: updateScheduleStatuses
summary: Atomically pause or resume the caller's current reminders
description: Applies one active or paused status to every requested schedule in the supplied order.
The calling Silicon must own every schedule, and every schedule must still be current. Validation
is all-or-nothing; failures leave the complete batch unchanged. The response contains one compact
status result per requested schedule in request order.
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/TestKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleStatusBatchUpdate'
responses:
'200':
description: Schedule status results in request order
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleStatusBatchUpdateResponse'
default:
$ref: '#/components/responses/Error'
post:
tags:
- Schedules
operationId: createSchedule
summary: Create a one-time or recurring reminder for the calling Silicon
description: Only a Silicon creates reminders, and only for itself. An IANA timezone is mandatory.
Provide the timezone field in the JSON request body, for example "timezone":"Asia/Kolkata". There is
no default timezone. Missing, null, or blank values return 422 timezone_required with guidance to
provide this field.
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/TestKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleCreate'
responses:
'201':
description: Schedule created
content:
application/json:
schema:
$ref: '#/components/schemas/Schedule'
default:
$ref: '#/components/responses/Error'
/schedules/{schedule_id}:
parameters:
- $ref: '#/components/parameters/ScheduleId'
get:
tags:
- Schedules
operationId: getSchedule
summary: Get a reminder the caller can read
description: Reminders the caller cannot read return the same not-found response as absent
identifiers. Accepts a verification proof with the remind.schedules.read scope.
security:
- bearerAuth: []
- proofAuth: []
parameters:
- $ref: '#/components/parameters/TestKey'
responses:
'200':
description: Schedule
content:
application/json:
schema:
$ref: '#/components/schemas/Schedule'
default:
$ref: '#/components/responses/Error'
patch:
tags:
- Schedules
operationId: updateSchedule
summary: Update a reminder of the calling Silicon
description: A readable reminder of another Silicon returns 403 not_reminder_owner.
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/TestKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
minProperties: 1
additionalProperties: false
properties:
text:
type: string
minLength: 1
timezone:
type: string
minLength: 1
description: IANA time-zone identifier
kind:
$ref: '#/components/schemas/ScheduleKind'
cron:
type: string
description: Five-field Linux cron expression
status:
$ref: '#/components/schemas/MutableScheduleStatus'
responses:
'200':
description: Updated schedule
content:
application/json:
schema:
$ref: '#/components/schemas/Schedule'
default:
$ref: '#/components/responses/Error'
delete:
tags:
- Schedules
operationId: archiveSchedule
summary: Archive a reminder of the calling Silicon for 45 days
description: The access token is checked with Silicon Accounts before the reminder is archived.
parameters:
- $ref: '#/components/parameters/TestKey'
responses:
'204':
description: Archived, or already archived
default:
$ref: '#/components/responses/Error'
/schedules/{schedule_id}/executions:
get:
tags:
- Executions
operationId: listScheduleExecutions
summary: List the delivery history of a reminder the caller can read
description: Visibility of the parent reminder is enforced before pagination. Accepts a
verification proof with the remind.schedules.read scope.
security:
- bearerAuth: []
- proofAuth: []
parameters:
- $ref: '#/components/parameters/ScheduleId'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/TestKey'
responses:
'200':
description: Execution history, newest first
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/Execution'
next_cursor:
type:
- string
- 'null'
default:
$ref: '#/components/responses/Error'
/auth/me:
get:
tags:
- Account
operationId: getIdentity
summary: Describe the calling account as Remind sees it
description: 'Returns the signed-in account, its custodian, whether it may write reminders and how
many Silicons it can read. Accepts a verification proof with the remind.schedules.read scope,
in which case credential is proof and issuing_app names the app that holds it. Responses use
Cache-Control: no-store.'
security:
- bearerAuth: []
- proofAuth: []
parameters:
- $ref: '#/components/parameters/TestKey'
responses:
'200':
description: The calling account
content:
application/json:
schema:
$ref: '#/components/schemas/Identity'
default:
$ref: '#/components/responses/Error'
/silicons:
get:
tags:
- Account
operationId: listSilicons
summary: List the Silicons whose reminders the caller can read
description: The caller itself (a Silicon), the Silicons it looks after (a Carbon), its siblings,
and Silicons that shared their reminders with it, ordered by uuid, with each one's retained
reminder count. Accepts a verification proof with the remind.schedules.read scope.
security:
- bearerAuth: []
- proofAuth: []
parameters:
- name: after
in: query
description: The next_cursor of the previous page.
schema:
$ref: '#/components/schemas/AccountUuid'
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- $ref: '#/components/parameters/TestKey'
responses:
'200':
description: Readable Silicons
content:
application/json:
schema:
type: object
required:
- items
- next_cursor
properties:
items:
type: array
items:
$ref: '#/components/schemas/VisibleSilicon'
next_cursor:
type:
- string
- 'null'
default:
$ref: '#/components/responses/Error'
/webhook:
get:
tags:
- Webhooks
operationId: getWebhook
summary: Read the calling Silicon's first delivery endpoint
description: Kept for older clients; GET /webhooks lists every subscription. The signing secret is
never returned.
parameters:
- $ref: '#/components/parameters/TestKey'
responses:
'200':
description: The first active subscription
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationInfo'
'409':
$ref: '#/components/responses/WebhookNotConfigured'
default:
$ref: '#/components/responses/Error'
put:
tags:
- Webhooks
operationId: configureWebhook
summary: Add a delivery endpoint for the calling Silicon
description: Kept for older clients; the same as POST /webhooks. The access token is checked with
Silicon Accounts first.
parameters:
- $ref: '#/components/parameters/TestKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationInput'
responses:
'201':
description: Subscription created
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationReceipt'
default:
$ref: '#/components/responses/Error'
delete:
tags:
- Webhooks
operationId: disableWebhook
summary: Disable every delivery endpoint of the calling Silicon
description: The access token is checked with Silicon Accounts first.
parameters:
- $ref: '#/components/parameters/TestKey'
responses:
'204':
description: Disabled, or none was active
default:
$ref: '#/components/responses/Error'
/webhooks:
get:
tags:
- Webhooks
operationId: listWebhooks
summary: List webhook subscriptions
description: A Silicon lists its own subscriptions. A Carbon lists, read-only, the subscriptions of
the Silicons it looks after; silicon_id narrows that to one of them. Signing secrets are never
returned.
parameters:
- name: silicon_id
in: query
description: The `si:` id or uuid of one Silicon the calling Carbon looks after.
schema:
type: string
minLength: 1
maxLength: 64
- $ref: '#/components/parameters/TestKey'
responses:
'200':
description: Active subscriptions, possibly empty
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookSubscriptions'
default:
$ref: '#/components/responses/Error'
post:
tags:
- Webhooks
operationId: subscribeWebhook
summary: Add a webhook subscription for the calling Silicon
description: Any number of subscriptions may be active; each due reminder is delivered to all of
them. The access token is checked with Silicon Accounts first.
parameters:
- $ref: '#/components/parameters/TestKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationInput'
responses:
'201':
description: Subscription created
content:
application/json:
schema:
$ref: '#/components/schemas/DestinationReceipt'
default:
$ref: '#/components/responses/Error'
/webhooks/{subscription_id}:
delete:
tags:
- Webhooks
operationId: unsubscribeWebhook
summary: Disable one webhook subscription of the calling Silicon
description: The access token is checked with Silicon Accounts first.
parameters:
- $ref: '#/components/parameters/TestKey'
- name: subscription_id
in: path
required: true
schema:
type: string
format: uuid
responses:
'204':
description: Subscription disabled
default:
$ref: '#/components/responses/Error'
/viewers:
get:
tags:
- Sharing
operationId: listViewers
summary: List who may read reminders shared by or with the caller
description: granted lists the grants on the caller's reminders (a Silicon) or on the reminders of
the Silicons it looks after (a Carbon); received lists the grants that let the caller read someone
else's reminders.
responses:
'200':
description: Active viewer grants
content:
application/json:
schema:
$ref: '#/components/schemas/ViewerGrants'
default:
$ref: '#/components/responses/Error'
post:
tags:
- Sharing
operationId: grantViewer
summary: Let an account read a Silicon's reminders
description: A Silicon shares its own reminders; a Carbon shares the reminders of a Silicon it looks
after and names it with silicon_id. Sharing with another Silicon from outside the owner's circle
needs that Silicon to allow the owner first (POST /allowed-accounts). Not available inside a test
environment. The access token is checked with Silicon Accounts first.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTargetRequest'
responses:
'201':
description: Grant created
content:
application/json:
schema:
$ref: '#/components/schemas/ViewerGrant'
'200':
description: The grant already existed
content:
application/json:
schema:
$ref: '#/components/schemas/ViewerGrant'
default:
$ref: '#/components/responses/Error'
/viewers/{viewer}:
delete:
tags:
- Sharing
operationId: revokeViewer
summary: Stop sharing a Silicon's reminders with an account
description: The viewer is a `c:` or `si:` id or a Silicon Accounts uuid. A Carbon names the Silicon
with silicon_id. Not available inside a test environment. The access token is checked with
Silicon Accounts first.
parameters:
- name: viewer
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 64
- $ref: '#/components/parameters/SiliconSelector'
responses:
'204':
description: Grant ended
default:
$ref: '#/components/responses/Error'
/allowed-accounts:
get:
tags:
- Sharing
operationId: listAllowedAccounts
summary: List the accounts allowed to share reminders with a Silicon
description: Silicons are not open to everyone. A Silicon's allow-list names the accounts from
outside its circle that may share reminders with it. A Silicon lists its own; a Carbon lists those
of the Silicons it looks after, or of one named with silicon_id.
parameters:
- $ref: '#/components/parameters/SiliconSelector'
responses:
'200':
description: Active allow-list entries
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/Allowance'
default:
$ref: '#/components/responses/Error'
post:
tags:
- Sharing
operationId: allowAccount
summary: Allow an account to share reminders with a Silicon
description: A Silicon allows for itself; its custodian names the Silicon with silicon_id. Not
available inside a test environment. The access token is checked with Silicon Accounts first.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountTargetRequest'
responses:
'201':
description: Entry created
content:
application/json:
schema:
$ref: '#/components/schemas/Allowance'
'200':
description: The entry already existed
content:
application/json:
schema:
$ref: '#/components/schemas/Allowance'
default:
$ref: '#/components/responses/Error'
/allowed-accounts/{account}:
delete:
tags:
- Sharing
operationId: disallowAccount
summary: Remove an account from a Silicon's allow-list
description: Also ends the grants that entry made possible. Not available inside a test environment.
The access token is checked with Silicon Accounts first.
parameters:
- name: account
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 64
- $ref: '#/components/parameters/SiliconSelector'
responses:
'204':
description: Entry removed
default:
$ref: '#/components/responses/Error'
/test-environments:
get:
tags:
- Test environments
operationId: listTestEnvironments
summary: List the test environments of the caller's circle
description: Environments the caller owns, those of the Silicons it looks after, of its siblings and
of its custodian. Send these requests without X-Remind-Test-Key.
parameters:
- $ref: '#/components/parameters/EnvironmentCursor'
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: include_deleted
in: query
schema:
type: boolean
default: false
responses:
'200':
description: Environments, oldest first
content:
application/json:
schema:
type: object
required:
- items
- next_cursor
properties:
items:
type: array
items:
$ref: '#/components/schemas/TestEnvironment'
next_cursor:
type:
- string
- 'null'
format: uuid
default:
$ref: '#/components/responses/Error'
post:
tags:
- Test environments
operationId: createTestEnvironment
summary: Create an empty test environment owned by the caller
description: 'The environment uses the caller''s Silicon Accounts sign-in; only its 32-character key
selects it. The key is returned once here and later from GET /test-environments/{id}/key, with
Cache-Control: no-store.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTestEnvironment'
responses:
'201':
description: Environment created
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentCreated'
default:
$ref: '#/components/responses/Error'
/test-environments/{id}:
parameters:
- $ref: '#/components/parameters/EnvironmentId'
get:
tags:
- Test environments
operationId: getTestEnvironment
summary: Read environment metadata
description: Any account of the owner's circle may read it, including during the 30-day recovery
window.
responses:
'200':
description: Environment
content:
application/json:
schema:
$ref: '#/components/schemas/TestEnvironment'
default:
$ref: '#/components/responses/Error'
delete:
tags:
- Test environments
operationId: deleteTestEnvironment
summary: Retire an environment for 30-day recovery
description: Only the owner or the owner's custodian. The access token is checked with Silicon
Accounts first.
responses:
'204':
description: Retired
default:
$ref: '#/components/responses/Error'
/test-environments/{id}/key:
get:
tags:
- Test environments
operationId: getEnvironmentKey
summary: Retrieve the active key
description: 'Any account of the owner''s circle. Keys are encrypted at rest and returned with
Cache-Control: no-store. The access token is checked with Silicon Accounts first.'
parameters:
- $ref: '#/components/parameters/EnvironmentId'
responses:
'200':
description: The active key
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentKey'
default:
$ref: '#/components/responses/Error'
/test-environments/{id}/key-rotations:
post:
tags:
- Test environments
operationId: rotateEnvironmentKey
summary: Rotate and revoke the previous key
description: 'Only the owner or the owner''s custodian. Returned with Cache-Control: no-store. The
access token is checked with Silicon Accounts first.'
parameters:
- $ref: '#/components/parameters/EnvironmentId'
responses:
'200':
description: The new key
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentKey'
default:
$ref: '#/components/responses/Error'
/test-environments/{id}/restorations:
post:
tags:
- Test environments
operationId: restoreEnvironment
summary: Recover a retired environment with a new key
description: 'Only the owner or the owner''s custodian, within 30 days of retirement. Returned with
Cache-Control: no-store. The access token is checked with Silicon Accounts first.'
parameters:
- $ref: '#/components/parameters/EnvironmentId'
responses:
'200':
description: The new key
content:
application/json:
schema:
$ref: '#/components/schemas/EnvironmentKey'
default:
$ref: '#/components/responses/Error'
/testing-environment:
get:
tags:
- Test environments
operationId: currentEnvironment
summary: Describe the selected test environment
description: Requires the environment key only. Omitting it returns test_environment_required. A
test environment holds at most 100 retained reminders; inactivity retires it after 15 days.
security:
- testKeyAuth: []
responses:
'200':
description: Environment
content:
application/json:
schema:
$ref: '#/components/schemas/TestEnvironment'
default:
$ref: '#/components/responses/Error'
/testing-environment/cleanings:
post:
tags:
- Test environments
operationId: cleanEnvironment
summary: Atomically clear all data of the selected test environment, keeping its key
description: Requires the environment key only. Omitting it returns test_environment_required.
security:
- testKeyAuth: []
responses:
'204':
description: Cleaned
default:
$ref: '#/components/responses/Error'
/health/live:
servers:
- url: https://api.remind.teamofsilicons.com
get:
tags:
- Operations
operationId: healthLive
summary: Check live status
security: []
responses:
'200':
description: The process is serving
content:
application/json:
schema:
$ref: '#/components/schemas/Health'
default:
$ref: '#/components/responses/Error'
/health/ready:
servers:
- url: https://api.remind.teamofsilicons.com
get:
tags:
- Operations
operationId: healthReady
summary: Check ready status
security: []
responses:
'200':
description: Dependencies are reachable
content:
application/json:
schema:
$ref: '#/components/schemas/Health'
default:
$ref: '#/components/responses/Error'
/webhook/:
servers:
- url: https://api.remind.teamofsilicons.com
post:
tags:
- Operations
operationId: receiveAccountsWebhook
summary: Receive Silicon Accounts app webhook deliveries
description: Silicon Accounts calls this route (POST /webhook works too) when an account Remind knows
changes its id, profile or custodian, signs out of Remind, loses access, or is deleted. The
signature is an HMAC-SHA256 of "{timestamp}.{raw body}" with Remind's webhook secret, checked over
the exact bytes with a five-minute tolerance. A missing, wrong or stale signature returns 401
webhook_signature_invalid; a signed body that is not an event returns 400 webhook_body_invalid.
Each event_id applies once; a repeat returns duplicate. Event types Remind does not use, and ping,
return ignored.
security: []
parameters:
- name: X-Accounts-Timestamp
in: header
required: true
description: Unix seconds when Silicon Accounts signed the delivery.
schema:
type: string
pattern: ^[0-9]{1,12}$
- name: X-Accounts-Signature
in: header
required: true
description: v1=<hex HMAC-SHA256>; several comma-separated values during a secret rotation.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountsEvent'
responses:
'200':
description: Applied, recognised as a duplicate, or ignored
content:
application/json:
schema:
$ref: '#/components/schemas/AccountsEventAccepted'
default:
$ref: '#/components/responses/Error'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
A Silicon Accounts access token issued to Remind (an EdDSA-signed JWT with audience remind and
the Silicon Accounts issuer). Sign in with `remind login`, or exchange a Silicon sign-in token
for Remind with Silicon Accounts. Remind verifies the signature against the published keys,
the audience, the issuer and the expiry; routes that change sharing, delivery endpoints, test
environment keys or archive reminders also ask Silicon Accounts whether the token is still
active. A token issued before the account signed out of Remind, lost access, or was deleted
is refused with token_revoked or account_deleted. Errors (401): unauthenticated, token_expired,
token_wrong_audience, token_wrong_issuer, token_unknown_key, token_bad_signature,
token_malformed, token_missing_claim, token_invalid, token_kind_mismatch, token_revoked,
account_deleted, legacy_token_rejected and proof_as_bearer; 503 when Silicon Accounts cannot
be reached to check a token.
proofAuth:
type: http
scheme: Proof
description: >-
`Authorization: Proof sap_…`: a verification proof another app obtained from Silicon Accounts
for Remind, with the remind.schedules.read scope. Remind verifies it with Silicon Accounts and
then answers with what the account the proof names can read. Proofs are accepted only on
GET /schedules, GET /schedules/{schedule_id}, GET /schedules/{schedule_id}/executions,
GET /silicons and GET /auth/me, only from the apps this Remind deployment trusts, and never
change anything. Errors: proof_not_accepted, proof_invalid, proof_scope_missing,
proof_issuer_not_allowed, proof_kind_not_accepted.
testKeyAuth:
type: apiKey
in: header
name: X-Remind-Test-Key
description: The 32-character key of a test environment. It selects the environment; ordinary
actions inside it still need a Silicon Accounts access token.
parameters:
ScheduleId:
name: schedule_id
in: path
required: true
schema:
type: string
format: uuid
EnvironmentId:
name: id
in: path
required: true
schema:
type: string
format: uuid
EnvironmentCursor:
name: after
in: query
description: The next_cursor of the previous page.
schema:
type: string
format: uuid
SiliconSelector:
name: silicon_id
in: query
description: Which Silicon this is about, by `si:` id or uuid. A Carbon must name one of the
Silicons it looks after; a Silicon may omit it or name itself.
schema:
type: string
minLength: 1
maxLength: 64
IdempotencyKey:
name: Idempotency-Key
in: header
required: true
schema:
type: string
minLength: 8
maxLength: 255
Cursor:
name: cursor
in: query
schema:
type: string
Limit:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
TestKey:
name: X-Remind-Test-Key
in: header
required: false
description: Selects a test environment by its 32-character key. Invalid, expired or revoked keys
fail closed with test_key_invalid. Environment management routes reject this header.
schema:
type: string
pattern: ^[a-zA-Z0-9]{32}$
responses:
WebhookNotConfigured:
description: The calling Silicon has no active webhook subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: webhook_not_configured
message: No active webhook subscription is configured.
request_id: 0199d8d5-2f62-7eb7-81c5-1e456778f8de
Error:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
BugReportRequest:
type: object
additionalProperties: false
required:
- message
properties:
message:
type: string
minLength: 1
maxLength: 16384
description: Reproduction details, maximum 16384 UTF-8 bytes. Exclude credentials.
pr:
type:
- string
- 'null'
pattern: ^https://github.com/teamofsilicons/silicon-remind/pull/[1-9][0-9]*$
BugReportResponse:
type: object
required:
- id
- status
- failure_reason
properties:
id:
type: string
format: uuid
status:
type: string
enum:
- queued
- sending
- sent
- failed
- simulated
failure_reason:
type:
- string
- 'null'
VersionDiscovery:
type: object
required:
- service
- current
- supported
- selection_header
- versions
properties:
service:
type: string
current:
type: integer
const: 2
supported:
type: array
items:
type: integer
protocol:
type: string
selection_header:
type: string
const: X-Remind-API-Version
versions:
type: array
items:
type: object
required:
- version
- status
- sunset_at
- implemented
properties:
version:
type: integer
status:
type: string
enum:
- active
- deprecated
- sunset
sunset_at:
type:
- string
- 'null'
format: date-time
implemented:
type: boolean
sunset_idle_days:
type: integer
policy:
type: string
format: uri
AccountUuid:
type: string
pattern: "^([A-Za-z0-9]{1,64}|[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$"
description: Permanent 128-bit Silicon Accounts UUID in canonical lowercase hyphenated form. Legacy short IDs are accepted only during the coordinated migration.
example: 550e8400-e29b-41d4-a716-446655440000
SiliconId:
type: string
pattern: ^si:[a-z0-9_-]{3,50}$
description: Public id of a Silicon. It can change; the uuid never does.
AccountKind:
type: string
enum:
- carbon
- silicon
AccountRef:
type: object
required:
- uuid
- id
- kind
properties:
uuid:
$ref: '#/components/schemas/AccountUuid'
id:
type: string
description: Current public id (c:handle or si:handle); empty when Remind does not know it yet.
kind:
oneOf:
- $ref: '#/components/schemas/AccountKind'
- type: 'null'
Relation:
type: string
description: Why the caller can read an account's reminders. self is the caller; custodian marks
a Silicon the calling Carbon looks after; sibling marks another Silicon of the calling Silicon's
custodian; shared marks a Silicon that granted the caller view.
enum:
- self
- custodian
- sibling
- shared
ScheduleStatus:
type: string
enum:
- active
- paused
- completed
ScheduleSection:
type: string
enum:
- current
- archived
MutableScheduleStatus:
type: string
enum:
- active
- paused
ScheduleStatusBatchUpdate:
type: object
required:
- schedule_ids
- status
additionalProperties: false
properties:
schedule_ids:
type: array
minItems: 1
maxItems: 100
uniqueItems: true
items:
type: string
format: uuid
status:
$ref: '#/components/schemas/MutableScheduleStatus'
ScheduleStatusBatchUpdateResponse:
type: object
required:
- items
additionalProperties: false
properties:
items:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/ScheduleStatusResult'
ScheduleStatusResult:
type: object
required:
- id
- status
- next_run_at
- updated_at
additionalProperties: false
properties:
id:
type: string
format: uuid
status:
$ref: '#/components/schemas/MutableScheduleStatus'
next_run_at:
type:
- string
- 'null'
format: date-time
updated_at:
type: string
format: date-time
ScheduleKind:
type: string
enum:
- one_time
- recurring
ScheduleCreate:
type: object
required:
- text
- kind
- cron
- timezone
additionalProperties: false
properties:
text:
type: string
minLength: 1
maxLength: 100000
kind:
$ref: '#/components/schemas/ScheduleKind'
cron:
type: string
description: Five-field Linux cron expression
timezone:
type: string
minLength: 1
description: Required IANA time-zone identifier. Provide timezone explicitly, for example
Asia/Kolkata or UTC; there is no default.
examples:
- Asia/Kolkata
Schedule:
allOf:
- $ref: '#/components/schemas/ScheduleCreate'
- type: object
required:
- id
- owner
- silicon_id
- timezone
- status
- section
- next_run_at
- archived_at
- purge_after
- created_at
- updated_at
properties:
id:
type: string
format: uuid
owner:
description: The Silicon that owns the reminder. null only for a reminder kept from before
Remind signed in with Silicon Accounts whose owner has not been matched to an account yet.
oneOf:
- $ref: '#/components/schemas/AccountRef'
- type: 'null'
silicon_id:
$ref: '#/components/schemas/SiliconId'
status:
$ref: '#/components/schemas/ScheduleStatus'
section:
$ref: '#/components/schemas/ScheduleSection'
next_run_at:
type:
- string
- 'null'
format: date-time
archived_at:
type:
- string
- 'null'
format: date-time
purge_after:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Execution:
type: object
required:
- id
- schedule_id
- scheduled_for
- status
properties:
id:
type: string
format: uuid
description: Stable idempotency identifier for this occurrence
schedule_id:
type: string
format: uuid
scheduled_for:
type: string
format: date-time
attempted_at:
type:
- string
- 'null'
format: date-time
delivered_at:
type:
- string
- 'null'
format: date-time
status:
type: string
enum:
- pending
- delivered
- retrying
- failed
hook_event_id:
type:
- string
- 'null'
format: uuid
failure_reason:
type:
- string
- 'null'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
message:
type: string
request_id:
type: string
Identity:
type: object
required:
- uuid
- kind
- id
- display_name
- pfp_url
- custodian
- can_manage_reminders
- credential
- issuing_app
- visible_silicons
properties:
uuid:
$ref: '#/components/schemas/AccountUuid'
kind:
$ref: '#/components/schemas/AccountKind'
id:
type: string
description: Current public id (c:handle or si:handle).
display_name:
type: string
pfp_url:
type: string
custodian:
description: The Carbon who looks after the calling Silicon; null for a Carbon.
oneOf:
- $ref: '#/components/schemas/AccountRef'
- type: 'null'
can_manage_reminders:
type: boolean
description: True for a Silicon signed in with an access token.
credential:
type: string
enum:
- access_token
- proof
issuing_app:
type:
- string
- 'null'
description: The app that holds the verification proof; null for an access token.
visible_silicons:
type: integer
minimum: 0
VisibleSilicon:
type: object
required:
- uuid
- silicon_id
- display_name
- pfp_url
- relation
- reminder_count
properties:
uuid:
$ref: '#/components/schemas/AccountUuid'
silicon_id:
type: string
description: Current si:handle id; empty when Remind does not know it yet.
display_name:
type: string
pfp_url:
type: string
relation:
$ref: '#/components/schemas/Relation'
reminder_count:
type: integer
minimum: 0
AccountTargetRequest:
type: object
additionalProperties: false
required:
- id
properties:
id:
type: string
minLength: 1
maxLength: 64
description: The other account, by c:handle, si:handle or Silicon Accounts uuid.
silicon_id:
type: string
minLength: 1
maxLength: 64
description: Which Silicon this is about. Required for a Carbon (one of the Silicons it looks
after); a Silicon may omit it.
ViewerGrant:
type: object
required:
- id
- owner
- viewer
- granted_by
- created_at
properties:
id:
type: string
format: uuid
owner:
$ref: '#/components/schemas/AccountRef'
viewer:
$ref: '#/components/schemas/AccountRef'
granted_by:
$ref: '#/components/schemas/AccountUuid'
created_at:
type: string
format: date-time
ViewerGrants:
type: object
required:
- granted
- received
properties:
granted:
type: array
items:
$ref: '#/components/schemas/ViewerGrant'
received:
type: array
items:
$ref: '#/components/schemas/ViewerGrant'
Allowance:
type: object
required:
- id
- silicon
- allowed
- created_by
- created_at
properties:
id:
type: string
format: uuid
silicon:
$ref: '#/components/schemas/AccountRef'
allowed:
$ref: '#/components/schemas/AccountRef'
created_by:
$ref: '#/components/schemas/AccountUuid'
created_at:
type: string
format: date-time
DestinationInput:
type: object
additionalProperties: false
required:
- endpoint_url
properties:
endpoint_url:
type: string
format: uri
description: Absolute https URL without credentials (http only for this machine outside
production).
signing_secret:
type: string
maxLength: 4096
writeOnly: true
description: Optional HMAC signing secret; omit for unsigned delivery. Never returned.
DestinationReceipt:
type: object
required:
- id
- silicon_id
- silicon_uuid
- version
- updated_at
properties:
id:
type: string
format: uuid
silicon_id:
$ref: '#/components/schemas/SiliconId'
silicon_uuid:
$ref: '#/components/schemas/AccountUuid'
version:
type: integer
updated_at:
type: string
format: date-time
DestinationInfo:
type: object
required:
- id
- silicon_id
- endpoint_url
- version
- updated_at
properties:
id:
type: string
format: uuid
silicon_id:
$ref: '#/components/schemas/SiliconId'
endpoint_url:
type: string
format: uri
version:
type: integer
updated_at:
type: string
format: date-time
WebhookSubscription:
type: object
required:
- id
- silicon_id
- owner
- endpoint_url
- version
- updated_at
properties:
id:
type: string
format: uuid
silicon_id:
$ref: '#/components/schemas/SiliconId'
owner:
oneOf:
- $ref: '#/components/schemas/AccountRef'
- type: 'null'
endpoint_url:
type: string
format: uri
version:
type: integer
updated_at:
type: string
format: date-time
WebhookSubscriptions:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/WebhookSubscription'
TestEnvironment:
type: object
required:
- id
- owner_uuid
- owner
- name
- description
- version
- created_at
- last_activity_at
- deleted_at
- purge_after
properties:
id:
type: string
format: uuid
owner_uuid:
oneOf:
- $ref: '#/components/schemas/AccountUuid'
- type: 'null'
owner:
oneOf:
- $ref: '#/components/schemas/AccountRef'
- type: 'null'
name:
type: string
description:
type:
- string
- 'null'
version:
type: integer
created_at:
type: string
format: date-time
last_activity_at:
type: string
format: date-time
deleted_at:
type:
- string
- 'null'
format: date-time
purge_after:
type:
- string
- 'null'
format: date-time
CreateTestEnvironment:
type: object
additionalProperties: false
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 100
description: Unique among the caller's active environments.
description:
type:
- string
- 'null'
maxLength: 10000
EnvironmentCreated:
type: object
required:
- environment
- key
properties:
environment:
$ref: '#/components/schemas/TestEnvironment'
key:
type: string
pattern: ^[a-zA-Z0-9]{32}$
EnvironmentKey:
type: object
required:
- environment_id
- key
properties:
environment_id:
type: string
format: uuid
key:
type: string
pattern: ^[a-zA-Z0-9]{32}$
Health:
type: object
required:
- service
- status
- version
properties:
service:
type: string
status:
type: string
version:
type: string
AccountsEvent:
type: object
required:
- event_id
- type
- data
properties:
event_id:
type: string
type:
type: string
description: account.id_changed, account.updated, account.deleted, membership.signed_out,
membership.access_removed, silicon.custodian_changed or ping; others are ignored.
occurred_at:
type: string
format: date-time
app_id:
type: string
silicon:
type:
- string
- 'null'
data:
type: object
AccountsEventAccepted:
type: object
required:
- event_id
- status
properties:
event_id:
type: string
status:
type: string
enum:
- processed
- duplicate
- ignored