Contributor API

Push your scraped events into Rifio

Have your own event scraper? Contribute events to Rifio via our REST API. Batch-submit up to 100 events per request and reach thousands of tech event seekers.

Quick Start

Get an API key

Generate an API key from your dashboard with the events:write scope.

POST your events

Send a JSON array of events to POST /api/v1/events with your key in the Authorization header.

Done

Your events are live on Rifio, searchable by text immediately. AI search enables after trust review.

Authentication

All requests require an API key passed in the Authorization header:

Authorization: Bearer rk_live_your_key_here

Your key must have the events:write scope. Generate a key in your dashboard.

Event Schema

Send a JSON body with an events array (1-100 items). Each event accepts these fields:

Field	Type	Required	Description
external_id	string	required	Your unique identifier for this event
source_url	string (URL)	required	Original event page URL
title	string	required	Event title (max 500 chars)
starts_at	string (ISO 8601)	required	Event start datetime, e.g. "2026-03-15T18:00:00Z"
platform	enum	optional	Source platform. Default: "other". Options: luma, eventbrite, meetup, ticketmaster, ics_feed, manual, other, ...
description	string	optional	Event description (max 10,000 chars)
ends_at	string (ISO 8601)	optional	Event end datetime
timezone	string	optional	IANA timezone, e.g. "Europe/London"
venue_name	string	optional	Venue or location name
city	string	optional	City name
country	string	optional	Country name
latitude	number	optional	Latitude (-90 to 90)
longitude	number	optional	Longitude (-180 to 180)
is_virtual	boolean	optional	Default: false
is_hybrid	boolean	optional	Both in-person and virtual
is_free	boolean	optional	Default: true
price_min	number	optional	Minimum ticket price
price_max	number	optional	Maximum ticket price
currency	string	optional	Default: "USD"
is_sold_out	boolean	optional	Whether event is sold out
event_type	string	optional	e.g. "conference", "meetup", "workshop"
categories	string[]	optional	Category tags (max 20)
tags	string[]	optional	Freeform tags (max 50)
topics	string[]	optional	Topic tags (max 20)
organiser_name	string	optional	Organiser or host name
organiser_url	string (URL)	optional	Organiser website
cover_image_url	string (URL)	optional	Cover image URL
attendee_count	number	optional	Current attendee/RSVP count
capacity	number	optional	Maximum capacity

Code Examples

curl -X POST https://rifio.dev/api/v1/events \
  -H "Authorization: Bearer rk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "external_id": "my-event-001",
        "source_url": "https://example.com/events/001",
        "title": "AI Meetup London",
        "starts_at": "2026-03-15T18:00:00Z",
        "city": "London",
        "country": "United Kingdom",
        "is_free": true,
        "organiser_name": "London AI Community",
        "categories": ["ai", "meetup"],
        "platform": "other"
      }
    ]
  }'

Response Format

Success (200)

{
  "data": {
    "inserted": 3,
    "updated": 1,
    "errors": []
  }
}

Validation Error (400)

{
  "error": "Validation failed",
  "details": [
    {
      "path": ["events", 0, "title"],
      "message": "title is required"
    }
  ]
}

401

Invalid or missing API key

403

API key lacks events:write scope

429

Rate limit exceeded

Trust & AI Search

To protect against spam and manage embedding costs, contributed events go through a lightweight trust model:

Immediate visibility

Your events appear on the site and are searchable via text search as soon as they are submitted.

AI search after review

New contributors start as untrusted. Your events won't appear in AI/semantic search results until we review your first batch and mark your key as trusted.

Automatic after trust

Once trusted, all your current and future events automatically get AI embeddings generated. No action needed on your end.

Rate Limits

requests per minute (default)

100

events per request (max batch size)

Exceeding the rate limit returns a 429 response. Duplicate events (same external_id + platform) are upserted, not rejected.

Ready to contribute events?

Generate an API key and start pushing events in minutes.

Get your API key Contact us