Open API

Using the eggX Open API

This wiki page will guide you through using the open API to most eggX resources. This API is "open" in a non-general way; the API is only accessibly by current or past eggX members.

Gearing up to connect to the API

To connect to the API, you will need at least 1 of the following:

• a server with an assigned machine-to-machine API key
• Both of the following:
  1. your eggX ID
  2. a browser capable of storing cookies

Obtaining an API key

In most use cases with the eggX API, you'll be making your requests from a browser application but in some cases you might need a server to act as a middleman between the eggX servers and yourself. To obtain an API key, send an email to security@eggx.io detailing exactly why you want to use the Open API via a server (don't forget to include your full name and eggX ID in the email).

If your request is accepted, you will be given an API key that is tied to your eggX ID. That key will have a scope granting you access to as many resources as we choose to grant to you. If your request is denied, not to worry. It's likely that your intended use of our resources didn't properly align with our policies. You're free to change your approach and try again.

Things to note

• The likelihood of successfully receiving an API key is slim
• We try to keep tight grips on how our resources are used. If you're unable to receive an API key, try another approach that doesn't require a server endpoint.
• Your API key will expire after 8 months. This is by design, you will be notified prior to the expiration date when you can submit a new request.

Caveats using the Open API

• You will not be able to post anything through the API. That is, you will not be able to alter our resources in any way
• Each connection is rate-limited, which means that you will only be able to make a certain number of requests each minute
• Vulnerable information (including names, addresses, contact URLs) is redacted from all requests
• Requests go through a proxy that monitors which requests are made and by whom
• Search requests for data are capped at an arbitrary amount

Connecting to the Open API

...

API Reference

Options

These options can be provided as part of your requests:

• populate
  • type: object
  • see: mongoose populate
• sort
  • type: object
  • see: mongoose sort
• skip
  • type: integer
  • see: mongoose skip
• limit
  • type: integer
  • see: mongoose limit

GET /open/fetch

This entrypoint is for retrieving individual documents using ObjectIds.

endpoint	resource	description
/domain/:id	Domain	Used in projects to categorize them
/draft/:id	Draft	Drafts are a set of eggX members who joined at the same time
/event/:id	Event	Physical/digital event to be hosted
/group/:id	Group	Collection of people (inc. staff)
/person/:id	Person	A human (much data here will be redacted)
/post/:id	Post	An article post
/project/:id	Project	A team's project
/tag/:id	Tag	Identifier used to categorize resources
/team/:id	Team	A team of people

/open/search

This entrypoint is for searching for collections of documents.

GET /domains

Resource: Domain Min num parameters: 0 Query parameters:

• name
  • type: string
  • matching: beginning of word
• externalUrl
  • type: string
  • matching: exact

GET /drafts

Resource: Draft Min num parameters: 1 Query parameters:

• name
  • type: string
  • matching: beginning of word
• start
  • type: integer >= 0
  • matching: draft start >=
• end
  • type: integer >= 0
  • matching: draft end <=

GET /events

Resource: Event Min num parameters: 1 Query parameters:

• title
  • type: string
  • matching: beginning of word
• schedule.start
  • type: integer >= 0
  • matching: event start >=
• schedule.end
  • type: integer >= 0
  • matching: event end <=
• people.author
  • type: ObjectId
• people.hosts
  • type: [ObjectId]
  • matching: contains all
• people.invitees
  • type: [ObjectId]
  • matching: contains all

GET /groups

Resource: Group Min num parameters: 0 Query parameters:

• name
  • type: string
  • matching: beginning of word
• people
  • type: [ObjectId]
  • matching: contains all

GET /people

Resource: Person Min num parameters: 0 Query parameters:

• name
  • type: string
  • matching: beginning of word

GET /posts

Resource: Post Min num parameters: 0 Query parameters:

• title
  • type: string
  • matching: beginning of word
• author
  • type: ObjectId

GET /projects

Resource: Project Min num parameters: 1 Query parameters:

• name
  • type: string
  • matching: beginning of word
• domain
  • type: string
  • matching: exact
• team
  • type: ObjectId

GET /tags

Resource: Tag Min num parameters: 0 Query parameters:

• name
  • type: string
  • matching: beginning of word
• domain
  • type: ObjectId

GET /teams

Resource: Team Min num parameters: 1 Query parameters:

• name
  • type: string
  • matching: beginning of word
• draft
  • type: ObjectId
• members
  • type: [ObjectId]
  • matching: contains all
• mentor
  • type: ObjectId