Alerts API: Getting Started

RedShip Alerts watches every new Reddit post and comment for your keywords and hands you each match, unscored, through webhooks, feeds and this API. It is a separate product from the RedShip App and needs an Alerts plan.

Authentication

Every request carries an API key created from your Alerts dashboard → API. Keys created in the RedShip App belong to an App project and get 403 wrong_product here.

Header

Authorization: Bearer rsp_your_api_key_here

Reads (GET) are limited to 60 requests per minute per key. The response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refused call answers 429 with Retry-After.

Base URL

https://redship.io/api/v1

Endpoints

GET/api/v1/keywordsList keywords POST/api/v1/keywordsCreate keywords (batch)PATCH/api/v1/keywords/:idUpdate a keyword DELETE/api/v1/keywords/:idDelete a keyword GET/api/v1/alertsList alerts GET/api/v1/alerts/:idGet one alert GET/api/v1/webhooksList webhooks POST/api/v1/webhooksCreate a webhook DELETE/api/v1/webhooks/:idDelete a webhook POST/api/v1/webhooks/:id/testSend a test delivery GET/api/v1/usagePlan, limits, today's counts

The 60-second version

1. Create keywords

curl -X POST https://redship.io/api/v1/keywords \
-H "Authorization: Bearer rsp_your_key" \
-H "Content-Type: application/json" \
-d '{"keywords":[{"text":"stripe webhook"},{"text":"notion alternative","mode":"proximity"}]}'

2. Point a webhook at your endpoint

curl -X POST https://redship.io/api/v1/webhooks \
-H "Authorization: Bearer rsp_your_key" \
-H "Content-Type: application/json" \
-d '{"name":"prod","url":"https://example.com/reddit-alerts"}'

3. Or poll

curl "https://redship.io/api/v1/alerts?limit=20" \
-H "Authorization: Bearer rsp_your_key"

Errors

All errors are JSON with a stable code:

{ "error": "Your plan allows 10 keywords", "code": "keyword_limit_reached" }

| Status | Code | Meaning | | --- | --- | --- | | 401 | unauthorized | Missing or invalid key | | 402 | subscription_required | The Alerts plan is not active | | 403 | wrong_product | The key belongs to a RedShip App project | | 403 | keyword_limit_reached | Re-activating a keyword would exceed the plan | | 404 | not_found | Unknown id, or not yours | | 422 | invalid_body | A field failed validation | | 429 | rate_limited | Slow down, see Retry-After |

Daily cap

Each keyword delivers up to 100 matches per UTC day. Beyond that, the overflow is dropped and only counted: it never reaches a webhook, a feed or GET /api/v1/alerts. GET /api/v1/usage shows, per keyword, how many were delivered and how many were held back today, which is how you spot a keyword that is too broad.