dogfooding-docs.joinswsh.com Open in urlscan Pro
2606:4700:10::6816:4f46  Public Scan

Form analysis
1 forms found in the DOM

GET https://dogfooding-docs.joinswsh.com/search.json

<form class="simple_form doc-search__form" data-action="ajax:success->doc-search#onPostSuccess ajax:error->doc-search#onPostError ajax:beforeSend->doc-search#onBeforeSend" data-doc-search-target="form"
  action="https://dogfooding-docs.joinswsh.com/search.json" accept-charset="UTF-8" data-remote="true" method="get">
  <svg width="14" height="14" fill="none" xmlns="http://www.w3.org/2000/svg" data-doc-search-target="searchIcon">
    <path d="m13 13-3-3M6.143 11.286A5.143 5.143 0 1 0 6.143 1a5.143 5.143 0 0 0 0 10.286Z" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"></path>
  </svg>
  <div class="loader doc-search__loader" aria-label="Loading" aria-live="assertive" aria-hidden="true" data-loader-type="bars" data-doc-search-target="loader"></div>
  <input label="false" autocomplete="off" type="hidden" name="uid" id="uid" value="0.754ce6c8b7137">
  <input label="false" autocomplete="off" autofocus="autofocus" data-doc-search-target="input" data-action="input->doc-search#submitOnType" class="string required" required="required" aria-required="true" placeholder="Search" type="text" name="query"
    id="query">
  <button type="button" class="esc-button" data-action="click->dialog#close">ESC</button>
</form>

Text Content

dogfooding swsh Public API Show Menu
Search… Ctrl+K

ESC





Example searches: “data”, “Api key auth”, “400”, “shareUrl”, “ownerId”


Toggle dark mode

--------------------------------------------------------------------------------

 * API Changelog

--------------------------------------------------------------------------------

Download source
 * JSON OpenAPI specification
 * YAML OpenAPI specification


TOPICS

 * Introduction
 * Authentication


ENDPOINTS

 * Album
   * Create a new album
     POST
   * Edit an existing album
     POST
   * Delete an existing album
     POST
   * Retrieve a specific album
     GET
   * Retrieve all albums the caller has access to
     GET
 * Ping
   * Ping the server
     GET

Powered by Bump.sh
Dismiss highlight Show more

--------------------------------------------------------------------------------

--------------------------------------------------------------------------------

--------------------------------------------------------------------------------



--------------------------------------------------------------------------------




--------------------------------------------------------------------------------


SWSH PUBLIC API DOCUMENTATION
0.0.4

Base URL

https://public-api.joinswsh.com


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 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's SDK
tools. You can install the SDK using your favorite package manager.

npm install @somewhere-somehow/swsh-public-api


import { SwshApiClient } from "swsh-public-api";

const client = new SwshApiClient({
    apiKey: "<YOUR_API_KEY>",
});
const { data } = await client.ping();


You can find the source code and report issues for the TypeScript client on
GitHub. The npm package can be found here.

AUTHENTICATION

Authentication is handled using an API key. You can create an API key in the
account settings 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.

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. 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.

import { SwshApiClient } from "swsh-public-api";

const client = new SwshApiClient({
    apiKey: "<YOUR_API_KEY>",
});


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. If you're using the TypeScript client, you may need to
send a custom fetch request to access response headers.

const res = await fetch("https://public-api.joinswsh.com/ping", {
    headers: {
        "x-api-key": "<YOUR_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. 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. 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.

This is the documentation for version 0.0.4 of the API. Last update on May 25,
2024.