Call the Rail Cove REST API
Create a scoped personal key, call the /api/v1 routes with a bearer header, and handle ownership, scope, expiry, and origin boundaries.
Follow the steps
Create a personal key from the signed-in API keys settings surface with only the scopes your script needs. Copy the one-time rail_sk_ value into a server-side secret store.
Set RAIL_COVE_API_BASE to https://YOUR_DEPLOYED_API_ORIGIN/api/v1, replacing the placeholder with the operator's real HTTPS API origin. For same-machine development, use http://localhost:4100/api/v1.
Send the key as Authorization: Bearer $RAIL_COVE_API_KEY. A first read-only check is GET $RAIL_COVE_API_BASE/boards.
Use GET /boards and GET /boards/:id with boards:read; GET /library and GET /library/search?q=... with library:read; and POST/PATCH/DELETE /library[/:id] with library:write.
Choose only the access you need
Personal keys always expire: the default is 90 days and the maximum is 365 days. Choose a non-empty subset of the available scopes and revoke the key when the connection is finished.
| Scope | What it allows |
|---|---|
boards:write | Capture selected web content to editable canvases. Also requires library:write. |
boards:read | List and read canvases the account can view. |
library:read | List and search the account’s own library. |
library:write | Create, update and delete library items through REST. |
Code examples
Replace placeholders in your own protected environment. Never paste a real key into a public page, browser bundle, prompt, screenshot, issue or repository.
export RAIL_COVE_API_BASE="http://localhost:4100/api/v1"
export RAIL_COVE_API_KEY="rail_sk_your_one_time_secret"
curl --fail --silent --show-error \
--header "Authorization: Bearer $RAIL_COVE_API_KEY" \
"$RAIL_COVE_API_BASE/boards"curl --fail --silent --show-error \
--request POST \
--header "Authorization: Bearer $RAIL_COVE_API_KEY" \
--header "Content-Type: application/json" \
--data '{"title":"Light study","type":"note","text":"Compare the morning shadows."}' \
"$RAIL_COVE_API_BASE/library"What to know
- The personal key path is intentionally narrower than the browser session API. There is no boards:write scope and no key access to account, billing, admin, uploads, jobs, or OAuth grant management.
- GET /api/v1/library/search?q=... returns an assets object. Library capture accepts note, link, and externally hosted image records; binary uploads remain in the session-authenticated upload flow.
- Board and library responses apply the same ownership and membership checks as the session API. Unverified users do not gain legacy membership access through a key.
- The placeholder YOUR_DEPLOYED_API_ORIGIN is documentation text, not a Rail Cove hosted service address. A remote client cannot reach a developer's localhost.
Troubleshooting
- 401 usually means the bearer header is missing, the key was copied incorrectly, or the key is expired, revoked, or tied to an unavailable account.
- 403 with an insufficient-scope error means the key does not include the scope required by the route. Create a new least-privilege key or choose a route covered by the current key.
- A request to /api/boards with a personal key fails by design. Use /api/v1/boards for personal-key REST access and reserve the ordinary /api path for browser sessions.
- Never print the key in logs or put it in a NEXT_PUBLIC_ variable, browser bundle, repository, screenshot, prompt, or issue.