<aside> ⚠️

Doc is in public review. May change slightly but unlikely to have breaking changes.

</aside>

Authorization

All requests must include the x-api-key header with a valid api key. Contact @matthew on farcaster to request one. API access is offered at the discretion of our team for the time being.

There is no rate limiting, but we reserve the right to if you make a high volume of requests.

Endpoints

GET /v1/event - gets info about a specific event

• Params

  • event_id: the id of the event

• Response type

  type EventApiResponse = {
  	success: boolean;
  	event: {
  	  id: string;
  	  title: string;
  	  image_url: string | null;
  	  description: string | null;
  	  start_date: string;
  	  start_time: string;
  	  end_date: string;
  	  end_time: string;
  	  time_zone: string;
  	  recurrence_rules: {
  	    day: "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
  	    time: string;
  	    frequency: "weekly" | "biweekly";
  	  }[];
  	  sessions: {
  	    recurrence_id: string;
  	    date: string; // format YYYY-MM-DD
  	    time: string; // format HH:mm
  	    is_canceled: boolean;
  	    override_title: string | null;
  	    override_description: string | null;
  	    override_date: string | null; // format YYYY-MM-DD
  	    override_time: string | null; // format HH:mm
  	  }[];
  	  link_to_join: string | null;
  	  place?: { id: string; name: string; address: string | null; city: string | null } | null;
  	  link_abbr: string | null;
  	  place_abbr?: string | null;
  	  channel: Channel | null;
  	  hosts: User[];
  	  waitlist: "off" | "auto" | "manual";
  	  guest_limit?: number;
  	  approved_nfts: {
  	    name: string | null;
  	    image_url: string | null;
  	    address: string;
  	    chain: string;
  	  }[];
  	  bg_color: string;
  	  text_color: string;
  	  text_theme: string;
  	  going_count: number;
  	};
  }
  

• Example query

  async function getEvent(event_id: string) {
    try {
      // get the api key
      const api_key = "[insert api key here]";
  
      // create the headers and endpoint for the request
      const headers = { "x-api-key": api_key };
      const endpoint = "<https://events.xyz/api/v1/event?event_id=>" + event_id;
  
      // make the request to @event api
      const response = await fetch(endpoint, { headers });
  
      // parse the response and continue
      const { success, event } = await response.json();
      
      // throw an error if request failed
      if (!success) {
  	    throw new Error("Farc! Couldn't find this event")
      }
  
      return event;
    } catch (e) {
      console.error(e);
    }
  }
  

GET /v1/rsvp - gets info about a specific rsvp

• Params

  • event_id: the id of the event
  • fid: the farcaster id of the user

• Response type

  type RsvpApiResponse = {
  	success: boolean;
  	rsvp: {
  		fid: number;
  		event_id: string;
  		status: "going" | "applied" | "not_going";
  	}
  }
  

• Example query

  async function getRsvp(event_id: string, fid: number) {
    try {
      // get the api key
      const api_key = "[insert api key here]";
  
      // create the headers and endpoint for the request
      const headers = { "x-api-key": api_key };
      const endpoint = `https://events.xyz/api/v1/rsvp?event_id=${event_id}&fid=${fid}`;
  
      // make the request to @event api
      const response = await fetch(endpoint, { headers });
  
      // parse the response and continue
      const { success, rsvp } = await response.json();
      
      // throw an error if request failed
      if (!success) {
  	    throw new Error("Farc! Couldn't find this RSVP")
      }
  
      return rsvp;
    } catch (e) {
      throw new Error("Farc! Couldn't find this RSVP")
    }
  }
  

GET /v1/going - gets a list of users going to an event

• Params
  • event_id: the id of the event