Installation

Install the SDK for your language, then create an authenticated client. Pick a language tab — your choice is remembered across every page.

Install

TypeScript

npm install @giveitsmaller/sdk

Requires Node.js 18+.

PHP

The SDK targets PSR-18 (HTTP client) and PSR-17 (HTTP factories) and discovers a concrete implementation via php-http/discovery. Install it alongside any PSR-18 client — Guzzle is the common choice:

composer require giveitsmaller/sdk guzzlehttp/guzzle http-interop/http-factory-guzzle

Requires PHP ^8.1. If you already have a PSR-18 client (e.g. Symfony HttpClient), inject it directly instead of installing Guzzle.

Python

Not available: the Python SDK is not published and no release is scheduled — see Python.

Rust

Not an application SDK: Rust is internal contract types — see Rust.

Authenticate

How you authenticate depends on where your code runs:

Your code runs…	Authenticate with	Why
on a server, a CLI, a worker (Node, PHP)	an API key	the key stays on a machine you control
in a user's browser	nothing — call your own backend instead; see In a browser	anything shipped to a browser is readable by whoever loads the page, and the API only accepts browser requests from GISL's own web app

On a server: an API key

Every server-side request is authenticated with an API key sent as a Bearer token. Get a key from the dashboard at giveitsmaller.com. Pass it when you create the client — the SDK sets the Authorization header on every request for you. The base URL defaults to https://api.giveitsmaller.com.

TypeScript

import { gisl } from '@giveitsmaller/sdk';

const client = await gisl.create({ apiKey: 'REPLACE_ME_API_KEY' });

The key resolves from the first source that provides one: the explicit apiKey, then the GISL_API_KEY environment variable, then the [default] profile in ~/.gisl/credentials (pick another with profile).

PHP

use Gisl\Sdk\Gisl;

// Explicit key:
$client = Gisl::create(apiKey: 'sk_live_...');

// Or rely on GISL_API_KEY / ~/.gisl/credentials:
$client = Gisl::create();

The key resolves from the first source that provides one: the explicit apiKey:, then GISL_API_KEY, then the [default] profile in ~/.gisl/credentials. With no key found, Gisl::create() throws GislMissingCredentialsError before any network call. Target a non-production environment with Gisl::create(apiKey: 'sk_...', environment: Environment::Staging).

Python

Not available. The Python SDK is not published and no release is scheduled — see Python.

Rust

Not an application SDK. The Rust output is internal contract types — see Rust.

In a browser

Never put an API key in browser code

An API key in frontend JavaScript is readable by anyone who opens the page, and it authenticates as your account. Keep it on your server.

Building a web app? Call GISL from your backend with an API key, and have your frontend talk to your backend. The API does not accept browser requests from third-party sites: CORS allows only GISL's own web app.

To show a result in your frontend, pass along its pre-signed output URL and link or display it (<a href>, <img src>). A fetch() of that URL from your own origin is blocked by the storage bucket's CORS.

The TypeScript SDK does have a browser entry with session-cookie auth (useSessionCookie: true), but that is for GISL's own web app. The session cookie is issued for .giveitsmaller.com with SameSite=Lax, so a browser will not send it from any other site. Details are in the TypeScript browser section.

Next

Head to the Quickstart to compress your first file end to end.