Getting Started

The Prospero API allows you to programmatically interact with a Prospero Organization. The API is RESTful and uses JSON to transport most data. It's the same API we use internally to build our applications.

You can use the Prospero API to build your own scripts, applications, and integrations with external systems.

Endpoint

Prospero's API endpoint is:

Code
 
https://api.prosperoapp.com

You can always GET the base endpoint to check the health of the API. It should return a 200 status code with the content "Hello, Prospero!".

Authentication

Prospero supports personal access & refresh tokens. We intend to support full OAuth2 authentication for third-party applications in the future.

Refer to Authentication for a detailed guide on how to obtain and use these tokens.

Error Handling

The Prospero API uses standard HTTP status codes to indicate the success or failure of a request. For example, a 200 "OK" indicates the request was successful. For more information on HTTP status codes, we recommend referring to the Mozilla HTTP status code documentation.

Unsuccessful requests will return a JSON object in the response payload with the following signature:

Code
 
interface ErrorResponse {
  /** The HTTP status code */
  status: number;
  error: string;
}

For example, if you send an invalid payload to create a resource, you might receive an error response like this:

Code
 
{
  "status": 400,
  "error": "JSON does not contain required fields in required format"
}

Use strongly-typed clients when possible to catch validation errors at development time, and always validate required fields to avoid runtime errors.

Identifiers

Each entity in Prospero has a globally unique identifier. These are v1 UUIDs. You can use a library like uuid to validate them.

Dates & Times

Prospero uses ISO 8601-compliant dates and times. In most cases, these are formatted in standard YYYY-MM-DDThh:mm:ssZ format, though some fields may contain isolated dates (YYYY-MM-DD) or times (hh:mm:ss). In all cases, the Prospero API expects and returns dates and times in UTC.

Get Started

Once you have obtained your access token, you can start interacting with the API.

Who Am I?

To introspect the current authenticated user, you can use the /auth/whoami endpoint:

Code
 
curl --request GET \
  --url https://api.prosperoapp.com/auth/whoami

Working with Events

To list Events in your Organization, use the /events endpoint with query parameters to limit your retrieval:

Code
 
curl --request GET \
  --url 'https://api.prosperoapp.com/events?window_start=2024-08-01T00:00:00Z&window_end=2024-09-01T00:00:00Z'

By inspecting the result, you can find Events you want to work with. Store their ids for later use.

To create a new Event, send a POST request to the /events endpoint:

Code
 
curl --request POST \
  --url https://api.prosperoapp.com/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": {
    "orgId": "00000000-0000-0000-0000-000000000000",
    "title": "Performance",
    "start": {
      "date": "2024-08-25"
    },
    "end": {
      "date": "2024-08-25"
    },
    "details": "<p>On Sale Sep. 1</p>",
    "status": 1,
    "flag": true,
    "draft": false,
    "locationIds": [
      "00000000-0000-0000-0000-000000000000"
    ],
    "projectsIds": [],
    "roleGroupIds": [],
    "roleIds": [],
    "groupIds": [],
    "personIds": [],
    "itemIds": ["00000000-0000-0000-0000-000000000000"],
    "consumables": [],
    "tagIds": [],
    "fileIds": []
  },
  "notification": {
    "to": [
      "[email protected]"
    ],
    "body": "Heads up!"
  }
}
'

This request will create a new Event and return its full state, including the newly assigned id, if the call was successful (201 status code).

Once you've created an Event or found an Event you want to update, you can send a PATCH request to the /events/:id endpoint. Prospero uses JSON merge patch semantics - that is, Prospero will only update the fields passed in the payload, and leave all unspecified fields unchanged.

Code
 
curl --request PATCH \
  --url https://api.prosperoapp.com/events/00000000-0000-0000-0000-000000000000 \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": {
    "flag": false,
  },
  "notification": {
    "to": [
      "[email protected]"
    ],
    "body": "Heads up!"
  }
}
'

Fetching Updates

If you're working on building an application which displays Prospero data and you want the information to update in (near) realtime, you have a few options. To prevent excessive usage of our API, we recommend that you be mindful about your implementation.

Lets say you're displaying a large number of Events in your application and want to update them:

Do:

• Register a programmatic webhook and get updates for all Events in the Organization. When you detect changes, update the Event information.
• If you have to fetch recent changes, order results by returning recently updated Events first.
• Filter Events in your request instead of fetching all Events and filtering in code.

Don't:

• Poll updates for each Event in the application. There should never be a reason to do this and your application might get rate limited. See the above tactics for better implementations.

If you have any questions, please reach out to us.