# swsh Public API Documentation ## Description This is version `0.0.9` of this API documentation. Last update on Sep 4, 2025. # Introduction The swsh Public API can be used to create, manage, and access resources on the swsh platform. The API acts as an extension of the swsh account the API key was created for. Therefore, all resources will be owned by that account. Because the API key is linked to a user account, all resources can be managed and accessed using the website and app clients as normal. If there's functionality missing from the API, you can use the website or app clients to manage resources manually. This API is designed for simplicity in user and developer experience. The goal is to allow end-users to interact with swsh without needing to create credentials or link their account. For the developer, we aim for a simple implementation process with minimal overhead. In the inspiration section, you can read about some potential integration examples that demonstrate these design philosophies. ## Getting Started 1. [Create an email-linked account](https://www.joinswsh.com/login/email?callback=%2Fsettings%3Fmodal%3DDeveloperSettings) to represent your product or organization (you may need to log out of your personal account before creating a new one) 2. Generate an API key and store it securely in your backend secret manager 3. (Optional) Install the TypeScript client (`npm install @somewhere-somehow/swsh-public-api`) 4. Start making requests to the API! ## Inspiration ### Calendar Integration Imagine you're building a product that helps you and your friends find a time to meet which creates a calendar event for that decided time. The user clicks on a button in your app that creates an event and automatically invites their selected friends using a third party calendar. You can use the swsh API to automatically create an album for the event which is linked in the calendar event description. Everyone invited to the event can simply click on the swsh link, create an account, and upload/view the photos for that event. As a developer, integration would be very simple. To get set up, follow the getting started steps for creating an account and API key. In your event creation endpoint, you would call the `/album/createAlbum` endpoint to create an album with the same name as the event. Then, when invoking the third party calendar API, you can include the `shareUrl` in the description. ### Event Ticketing Platform Imagine you're building a platform that allows users to create and sell tickets for events. You can use the swsh API to create an album for each event to allow users to upload and view photos for that event. When a user buys a ticket, you can include the `shareUrl` in the ticket email. This way, the user can view photos of the event after it's over. If your event has a professional photographer, they can upload the photos to the generated swsh album for users to view and download. If there's a page where they can view their tickets, you can include the `shareUrl` there as well. To integrate this into your product, follow the getting started steps for creating an account and API key. On your event creation endpoint, you would call the `/album/createAlbum` endpoint to create an album with the same name as the event. You can store the `shareUrl` on the event object for later use. When a user buys a ticket, you can include the cached `shareUrl` in the ticket email. If you have a page where users can view their tickets, you can present the cached `shareUrl` there as well. ## Client For your convenience, we have an auto-generated TypeScript library you can use to interact with the API. Functions map directly to their corresponding API route, unless otherwise noted. The TypeScript SDK only supports ESM and is meant to be used in backend environments. Our client is generated using [Fern](https://buildwithfern.com)'s SDK tools. You can install the SDK using your favorite package manager. ```bash npm install @somewhere-somehow/swsh-public-api ``` ```typescript import { SwshApiClient } from "swsh-public-api"; const client = new SwshApiClient({ apiKey: "", }); const { data } = await client.ping(); ``` You can find the source code and report issues for the TypeScript client on [GitHub](https://github.com/somewhere-somehow-cal/swsh-public-api). The npm package can be found [here](https://www.npmjs.com/package/@somewhere-somehow/swsh-public-api). ## Authentication Authentication is handled using an API key. You can create an API key in the [account settings](https://www.joinswsh.com/settings?modal=DeveloperSettings) page. The API key is used to authenticate all requests to the API. The API key should be kept secret and not shared with anyone. Do not send requests from frontend environments. If you believe your API key has been compromised, you can delete it in the developer settings section of the [settings page](https://www.joinswsh.com/settings?modal=DeveloperSettings). All developer accounts must have a verified email address to create an API key. We strongly recommend against using your personal swsh account if you represent an organization. Instead, you can create a new account using an email address [here](https://www.joinswsh.com/login/email?callback=%2Fsettings%3Fmodal%3DDeveloperSettings). You may need to log out before creating a new account. The API key is passed in the `x-api-key` header of each request. If you're using the TypeScript client, you can set the API key for the client during initialization in the `apiKey` field. ```typescript import { SwshApiClient } from "swsh-public-api"; const client = new SwshApiClient({ apiKey: "", }); ``` ## Rate Limit The API has a rate limit enforced on every request. This rate limit is subject to change at any point. You can view the rate limit using the `x-rate-limit-consumed` and `x-rate-limit-remaining` headers on every request. If you exceed the rate limit, you will receive a `429 Too Many Requests` response. If you receive this response, you should wait until the rate limit resets before making more requests. Rate limits are specific to each account, so cycling API keys will not increase your limit. If you would like to have your rate limit increased, [contact us](https://www.joinswsh.com/contact). If you're using the TypeScript client, you may need to send a custom `fetch` request to access response headers. ```typescript const res = await fetch("https://public-api.joinswsh.com/ping", { headers: { "x-api-key": "", }, }); const numRemaining = Number(res.headers.get("x-rate-limit-remaining")); const numConsumed = Number(res.headers.get("x-rate-limit-consumed")); const periodEnd = Number(res.headers.get("x-rate-limit-period-end")); ``` ### Rate Limit Headers - `x-rate-limit-consumed`: The number of requests consumed in the current rate limit window. - `x-rate-limit-remaining`: The number of requests remaining in the current rate limit window. - `x-rate-limit-period-end`: The time at which the current rate limit window ends in seconds since the Unix epoch. ## Status You can view the uptime status of our public API on our [status page](https://status.joinswsh.com). We also offer a `/ping` endpoint to check if the API is online. ## Feedback If you have any questions, need help, or would like to request additional API functionality, you can contact us [here](https://www.joinswsh.com/contact). Also, you can just email me (hi, I'm Nathan!) at nathan (@) joinswsh.com. I'm happy to hop on call to walk you through implementation or help you with any issues you're facing. ## Servers - Production server: https://public-api.joinswsh.com (Production server) ## Authentication ## Endpoints and operations ### [Album](https://docs.joinswsh.com/group/endpoint-album.md) - [Create a new album](https://docs.joinswsh.com/operation/operation-createalbum.md) - [Edit an existing album](https://docs.joinswsh.com/operation/operation-editalbum.md) - [Delete an existing album](https://docs.joinswsh.com/operation/operation-deletealbum.md) - [Retrieve a specific album](https://docs.joinswsh.com/operation/operation-getalbum.md) - [Retrieve all albums the caller has access to](https://docs.joinswsh.com/operation/operation-getalbums.md) - [Retrieve preview photos for a specific album](https://docs.joinswsh.com/operation/operation-getpreviewphotos.md) - [Retrieve photos for a specific album](https://docs.joinswsh.com/operation/operation-getphotos.md) ### [Photo](https://docs.joinswsh.com/group/endpoint-photo.md) - [Checks if a photo has a specific label.](https://docs.joinswsh.com/operation/operation-checkphotolabel.md) - [Add a label to a photo. Requires admin access to the album.](https://docs.joinswsh.com/operation/operation-addphotolabel.md) - [Remove a label from a photo. Requires admin access to the album.](https://docs.joinswsh.com/operation/operation-removephotolabel.md) ### [Ping](https://docs.joinswsh.com/group/endpoint-ping.md) - [Ping the server](https://docs.joinswsh.com/operation/operation-ping.md) ### [Webhook](https://docs.joinswsh.com/group/endpoint-webhook.md) - [Subscribe to a webhook](https://docs.joinswsh.com/operation/operation-createsubscription.md) - [Retrieve all webhook subscriptions for the caller](https://docs.joinswsh.com/operation/operation-getsubscriptions.md) - [Delete a webhook subscription](https://docs.joinswsh.com/operation/operation-deletesubscription.md) ## Webhooks ### [New album](https://docs.joinswsh.com/group/webhook-new-album.md) - [A new album has been created](https://docs.joinswsh.com/operation/operation-post-newAlbum.md) ### [New photo](https://docs.joinswsh.com/group/webhook-new-photo.md) - [A new photo has been added to the album](https://docs.joinswsh.com/operation/operation-post-newPhoto.md) ### [Photo label added](https://docs.joinswsh.com/group/webhook-photo-label-added.md) - [A label has been added to an Active photo in an album](https://docs.joinswsh.com/operation/operation-post-photoLabelAdded.md) [Powered by Bump.sh](https://bump.sh)