Rokka

https://rokka.io/documentation
Admin
Rokka is an image processing and delivery service that provides an API, client libraries, and...
Tokens:98,336
Snippets:575
Trust Score:8.5
Update:8 months ago
Show doc for...
Tokens:
Raw
### Example Remote Image URL with Full URL Allow

Source: https://rokka.io/documentation/references/stacks

Shows a concrete example of a rokka URL rendering a remote image using the `remote_fullurl_allow` configuration, including the full remote URL.

```plaintext
https://mycompany.rokka.io/somestack/-https://blog.liip.ch/content/uploads/2017/06/Relax_sabbatical.jpg-/some-seo-string.jpg
```

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

### Install Rokka PHP Client Library

Source: https://rokka.io/documentation/guides/php-client-library-intro

Instructions for installing the Rokka PHP client library using Composer. This is the primary method for integrating Rokka's image manipulation capabilities into PHP applications.

```bash
composer require rokka/client
```

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

### Example Remote Image URL with Base Path

Source: https://rokka.io/documentation/references/stacks

Demonstrates a concrete example of a rokka URL rendering a remote image using the `remote_basepath` configuration.

```plaintext
https://mycompany.rokka.io/somestack/-2017/06/Relax_sabbatical.jpg-/some-seo-string.jpg
```

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

### User Registration API

Source: https://rokka.io/documentation/guides/get-started

Registers a new user with rokka.io and creates an organization. This is the first step to using the service.

```APIDOC
## POST /users

### Description
Registers a new user and creates an organization for them. This is a prerequisite for using the rokka.io service.

### Method
POST

### Endpoint
https://api.rokka.io/users

### Parameters
#### Request Body
- **email** (string) - Required - The email address of the user.
- **organization** (string) - Required - The name of the organization to be created.

### Request Example
```json
{
  "email": "my@email.com",
  "organization": "example-organization"
}
```

### Response
#### Success Response (200)
- **apiKey** (string) - The API key generated for the user.
- **organization** (string) - The name of the created organization.

#### Response Example
```json
{
  "apiKey": "your_generated_api_key",
  "organization": "example-organization"
}
```
```

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

### Example Render URL for Flexible Sizing (Rokkka)

Source: https://rokka.io/documentation/guides/best-practices-for-stack-configurations

This example shows a Rokkka render URL that utilizes stack variables to dynamically adjust image dimensions. By appending parameters like '/v-w-1200' or '/v-w-1000-h-800', you can control the width, height, and aspect ratio of the rendered image without modifying the base stack configuration.

```text
https://{organization}.rokka.io/{stack-name}/v-w-1200-h-900-crop-width-1200-height-900/{hash}.{format}
```

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

### Example JSON Response for a Stack

Source: https://rokka.io/documentation/references/stacks

This is an example of the JSON structure returned when a stack is successfully retrieved from the rokka.io API. It includes details like organization, stack name, creation timestamp, stack operations, and API links.

```json
{
    organization: "testorganization",
    name: "teststack",
    created: {
        date: "2015-08-20 08:50:32.000000",
        timezone_type: 3,
        timezone: "UTC"
    },
    stackoperations: [
        {
            name: "resize",
            options: {
                width: 200,
                height: 200
            }
        },
        {
            name: "rotate",
            options: {
                angle: 45
            }
        }
    ],
    _links: {
        self: {
            href: "/stacks/testorganization/teststack"
        }
    }
}
```

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

### Animated GIF Rendering Stack Configuration

Source: https://rokka.io/documentation/references/render

These JSON configurations define how to render animated GIFs. The first example shows a basic setup for auto-formatting to optimize output size. The second example includes operations like watermarking and resizing.

```json
{
    "stack_operations": [],
    "stack_options": {
        "autoformat": true
    }
}
```

```json
{
    "stack_operations": [
        {
            "name": "composition",
            "options": {
                "mode": "background",
                "secondary_image": "0dee47",
                "anchor": "right_bottom"
            }
        },
        {
            "name": "resize",
            "options": {
                "width": 300
            }
        }
    ],
    "stack_options": {
        "autoformat": true
    }
}
```

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

### Render Image with Rokka URL

Source: https://rokka.io/documentation/guides/php-client-library-intro

These examples demonstrate how to render images using Rokka's dynamic URLs. They show basic rendering, resizing, format changes, and applying stack options like DPR for retina displays. Replace `$YOUR_ORG` and the image hash accordingly.

```url
http://$YOUR_ORG.rokka.io/dynamic/dba893.jpg

```

```url
http://$YOUR_ORG.rokka.io/dynamic/resize-width-200/dba893.jpg

```

```url
http://$YOUR_ORG.rokka.io/dynamic/resize-width-200/dba893/someone-on-a-balcony.png

```

```url
https://$YOUR_ORG.rokka.io/dynamic/resize-width-200--options-dpr-2/dba893.png

```

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

### Register User and Create Organization via curl

Source: https://rokka.io/documentation/guides/get-started

This snippet demonstrates how to register a new user and create an organization using the rokka Management API via curl. It requires a JSON payload with the user's email and desired organization name. The response contains the API key necessary for subsequent operations.

```bash
curl -H 'Content-Type: application/json' -X POST 'https://api.rokka.io/users' -d '[
    {
        "email": "my@email.com",
        "organization": "example-organization"
    }
]'
```

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

### Retrieve a Stack using PHP SDK

Source: https://rokka.io/documentation/references/stacks

This PHP code example shows how to fetch a stack configuration using the rokka PHP client library. It initializes the client with organization credentials and then calls the getStack method. The retrieved stack object's name is printed, followed by its full details.

```php
$client = RokkaClientFactory::getImageClient('testorganization', 'apiKey');

$stack = $client->getStack('teststack');

echo 'Displaying stack ' . $stack->getName() . PHP_EOL;
print_r($stack);
```

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

### Create a Stack for Image Resizing

Source: https://rokka.io/documentation/guides/upload-and-render-an-image

Creates a new image stack with a specified name and operations. This example demonstrates creating a 'thumbnail' stack that resizes images to 200x200 pixels. The stack definition can include multiple operations applied in order. A successful request returns the stack definition.

```bash
curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/stacks/testorganization/thumbnail' -d '[
    {
        "name": "resize",
        "options": {
            "width": 200,
            "height": 200
        }
    }
]'
```

```php
$resize = new RokkaClientCoreStackOperation('resize', ['width' => 200, 'height' => 200]);
$stack = new RokkaClientCoreStack();
$stack->setName('thumbnail')->addStackOperation($resize);

$stack = $client->saveStack($stack);

var_dump($stack); 

```

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

### List Stacks using PHP SDK

Source: https://rokka.io/documentation/references/stacks

This PHP code snippet shows how to list stacks for an organization using the rokka.io PHP SDK. It initializes the client with the organization and API key, then iterates through the retrieved stacks, printing their names. Ensure the rokka/client library is installed.

```php
use Rokka\Client\Core\Stack;

$client = \Rokka\Client\Factory::getImageClient('testorganization', 'apiKey');

$stacks = $client->listStacks();

foreach ($stacks as $stack) {
    /** @var Stack $stack */
    echo 'Stack ' . $stack->getName() . PHP_EOL;
}
```

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

### Dynamic Stack Options with Expressions (JSON)

Source: https://rokka.io/documentation/references/stacks

This JSON configuration shows how to dynamically adjust stack options, such as 'optim.quality', based on expressions. It allows for conditional overrides, for example, reducing JPEG quality for high-resolution screens. Expressions are applied sequentially, with later matches overriding earlier ones.

```json
{
     "operations": [
         {
             "name": "resize",
             "options": {
                 "width": 200,
                 "height": 200
             }
         }
     ],
     "options": {
         "optim.quality": 4,
         "autoformat": true
     },
     "expressions": [ {
         "expression": "options.dpr >= 2",
             "overrides": {
                "options": {
                   "optim.quality": 2
                }
             }
         }
     ]
}
```

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

### Overwrite Stack Options in URL

Source: https://rokka.io/documentation/references/render

This example shows how to overwrite specific stack operation options directly within the rendering URL. It allows for granular control over transformations like 'resize-width' without altering the base stack configuration.

```bash
'https://{organization}.rokka.io/{stack-name}/resize-width-200--options-dpr-2-autoformat-true/{hash}.{format}'
```

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

### Custom LocalImage Implementation for External Sources (PHP)

Source: https://rokka.io/documentation/guides/php-client-library-intro

Provides an example of implementing the AbstractLocalImage class to handle images not stored locally, such as those in AWS S3 or a database. This allows rokka to fetch and process content from various external sources.

```php
class myDBImage extends RokkaClientLocalImageAbstractLocalImage {
    public function getContent()
    {
        // getContentFromDB() has to be implemented by you as well
        return $this->getContentFromDB($this->identifier);
    }
}


```

```php
<img src="<?= $rokka->getStackUrl(new myDBImage('someKeyToLookUpInDB'), 'test-stack');?>">

```

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

### AND Filtering by Size and Name (curl)

Source: https://rokka.io/documentation/references/searching-images

Filters images based on multiple criteria combined with an AND logic. This example returns images with a size greater than or equal to 30000 bytes AND a name starting with 'foo'.

```curl
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?size=[30000,}&name=foo*'
```

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

### Login to Rokka CLI

Source: https://rokka.io/documentation/guides/php-client-library-intro

This command configures the Rokka CLI with your API key, enabling authentication for subsequent operations. Ensure you replace `$YOUR_API_KEY` with your actual Rokka API key.

```bash
rokka login --apiKey $YOUR_API_KEY

```

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

### Create a Rokka Stack with Resize and Rotate Operations (PHP)

Source: https://rokka.io/documentation/references/stacks

This PHP code snippet shows how to programmatically create a Rokka stack using the Rokka client library. It defines resize and rotate operations, sets JPG quality options, and saves the stack configuration using the client. It requires the Rokka client library to be installed.

```php
use Rokka\Client\Core\Stack;
use Rokka\Client\Core\StackOperation;

$client = \Rokka\Client\Factory::getImageClient('mycompany', 'apiKey');

$stack = new Stack(null, 'teststack');

$stack->addStackOperation(new StackOperation('resize', ['width' => 200, 'height' => 200]));
$stack->addStackOperation(new StackOperation('rotate', ['angle' => 45]));
$stack->setStackOptions(['jpg.quality' => 80]);

$stack = $client->saveStack($stack);

echo 'Created stack ' . $stack->getName() . PHP_EOL;
print_r($stack);

```

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

### Get Current User ID with cURL

Source: https://rokka.io/documentation/references/users-and-memberships

Retrieves the unique user ID of the currently authenticated user by making a GET request to the /user endpoint. For security and privacy, only the user_id is returned.

```bash
curl 'https://api.rokka.io/user'
```

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

### Configure Stack for Remote Images (Base Path)

Source: https://rokka.io/documentation/references/stacks

Configures a base path for remote images on a specific stack. This allows different remote image sources for different stacks.

```bash
curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/stacks/mycompany/teststack' -d '{
    "operations":
    [
        {
            "name": "resize",
            "options": {
                "width": 200,
            }
        }
    ],
    "options": {
        "remote_basepath": $REMOTE_BASEPATH
    }
}'
```

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

### Get Current User ID

Source: https://rokka.io/documentation/references/users-and-memberships

Retrieves the user ID of the currently authenticated user.

```APIDOC
## GET /user

### Description
Retrieves the user ID of the currently logged-in user. For security reasons, only the user ID is returned.

### Method
GET

### Endpoint
/user

### Parameters
None

### Response
#### Success Response (200)
- **user_id** (string) - The unique identifier of the current user.

#### Response Example
```json
{
    "user_id": "271cce77-45c7-4f6d-a0f6-a4edc29964e6"
}
```
```

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

### Create a Rokka Image Stack

Source: https://rokka.io/documentation/guides/php-client-library-intro

This snippet demonstrates how to create a new image stack in Rokka.io using the command line. It defines a stack named 'test-stack' with a single 'resize' operation to a width of 200px. The input is a JSON payload piped to the 'rokka stacks create' command.

```bash
echo '{
  "options": {},
  "operations": [
    {
      "name": "resize",
      "options": {
        "width": 200
      }
    }
  ]
}' | rokka stacks create $YOUR_ORG test-stack
```

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

### Configure Organization for Remote Images (Base Path)

Source: https://rokka.io/documentation/references/stacks

Sets a base path for remote images, allowing rokka to fetch images by appending the remaining path. This is configured globally for the organization.

```bash
curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/organizations/mycompany/options' -d '{"remote_basepath": $REMOTE_BASEPATH"}'
```

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

### GET /sourceimages/{organization}/{hash}

Source: https://rokka.io/documentation/references/source-images

Retrieves metadata about a specific source image using its organization and hash.

```APIDOC
## GET /sourceimages/{organization}/{hash}

### Description
Retrieves meta data about a source image by providing the identifying hash and organization.

### Method
GET

### Endpoint
`/sourceimages/{organization}/{hash}`

### Parameters
#### Path Parameters
- **organization** (string) - Required - The name of the organization.
- **hash** (string) - Required - The unique hash of the source image.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET 'https://api.rokka.io/sourceimages/mycompany/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5'
```

### Response
#### Success Response (200)
- **hash** (string) - The unique hash of the source image.
- **short_hash** (string) - A shorter version of the hash.
- **binary_hash** (string) - The hash of the image binary data.
- **created** (string) - The timestamp when the image was created.
- **name** (string) - The original filename of the image.
- **mimetype** (string) - The MIME type of the image.
- **format** (string) - The image format (e.g., png, jpg).
- **size** (integer) - The size of the image in bytes.
- **width** (integer) - The width of the image in pixels.
- **height** (integer) - The height of the image in pixels.
- **organization** (string) - The organization the image belongs to.
- **link** (string) - A link to the source image resource.

#### Response Example
```json
{
    "hash": "c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5",
    "short_hash": "c03683",
    "binary_hash": "03b3e8a0bdd76ef55c021066642c9d2fa9c02799",
    "created": "2015-08-24T12:17:12+0000",
    "name": "image1.png",
    "mimetype": "image/jpeg",
    "format": "png",
    "size": 131284,
    "width": 800,
    "height": 1160,
    "organization": "mycompany",
    "link": "/sourceimages/mycompany/c412d8d6e4b9b7b058320b06972ac0ec72cfe6e5"
}
```
```

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

### Getting Blurhash from Rendered Image

Source: https://rokka.io/documentation/references/render

Retrieves a blurhash representation of a rendered image, useful for displaying low-resolution placeholders.

```APIDOC
## GET /websites/rokka_io/{organization}/{stack-name}/{hash}.blurhash

### Description
Generates and returns the blurhash for a rendered image.

### Method
GET

### Endpoint
`https://{organization}.rokka.io/{stack-name}/{hash}.blurhash`

### Parameters
#### Path Parameters
- **organization** (string) - Required - Your rokka.io organization name.
- **stack-name** (string) - Required - The name of the stack to use for rendering before generating the blurhash.
- **hash** (string) - Required - The hash (full or short) of the source image.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET 'https://{organization}.rokka.io/{stack-name}/{hash}.blurhash'
```

### Response
#### Success Response (200)
- **blurhash** (string) - The generated blurhash string.

#### Response Example
```json
{
  "blurhash": "LKO2?U%MRjIU00ayjEj?ayjqk9j?"
}
```
```

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

### Configure Stack for Remote Images (Full URL)

Source: https://rokka.io/documentation/references/stacks

Enables rokka to fetch images from any public URL on a per-stack basis. `remote_fullurl_whitelist` can be used to specify allowed domains. This allows for different remote image policies across stacks.

```bash
curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/stacks/mycompany/teststack' -d '{
    "operations":
    [
        {
            "name": "resize",
            "options": {
                "width": 200,
            }
        }
    ],
    "options": {
       "remote_fullurl_allow": true,
       "remote_fullurl_whitelist": ["\.rokka\.io"]
    }
}'
```

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

### Get Currently Used API Key Info

Source: https://rokka.io/documentation/references/users-and-memberships

Retrieves information about the API key that is currently being used for authentication.

```APIDOC
## GET /user/apikeys/current

### Description
Retrieves information about the API key currently in use for authentication.

### Method
GET

### Endpoint
/user/apikeys/current

### Response
#### Success Response (200)
- **API Key object** - Contains details about the current API key (e.g., id, comment).

#### Response Example
```json
{
  "id": "current_key_id",
  "comment": "current key comment"
}
```
```

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

### Output as Video

Source: https://rokka.io/documentation/references/render

To save bandwidth, animations can be displayed as videos using the HTML `<video>` tag. This section provides an example of how to implement this.

```APIDOC
## Output as Video

### Description
Display animations as video to reduce file size and save bandwidth. This is achieved using the HTML `<video>` tag.

### Method
N/A (Client-side HTML)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```html
<video autoplay loop muted playsinline poster="https://yourorg.rokka.io/animation/options-autoformat-false/12a82d.jpg">
    <source src="https://yourorg.rokka.io/animation/12a82d.webm" type="video/webm">
    <source src="https://yourorg.rokka.io/animation/12a82d.mp4" type="video/mp4">
</video>
```

### Response
N/A
```

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

### Create a Stack

Source: https://rokka.io/documentation/guides/upload-and-render-an-image

Creates a new image stack with specified operations for an organization. Stacks define how images are transformed upon rendering.

```APIDOC
## PUT /stacks/{organization}/{stack_name}

### Description
Creates a new image stack with specified operations for an organization. Stacks define how images are transformed upon rendering.

### Method
PUT

### Endpoint
`/stacks/{organization}/{stack_name}`

### Parameters
#### Path Parameters
- **organization** (string) - Required - The name of the organization.
- **stack_name** (string) - Required - The name of the stack to create or update.

#### Query Parameters
None

#### Request Body
- **operations** (array) - Required - An array of stack operation objects.
  - **name** (string) - Required - The name of the operation (e.g., 'resize').
  - **options** (object) - Optional - Options for the operation (e.g., {'width': 200, 'height': 200}).

### Request Example
```bash
curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/stacks/testorganization/thumbnail' -d '[
    {
        "name": "resize",
        "options": {
            "width": 200,
            "height": 200
        }
    }
]'
```

### Response
#### Success Response (200)
- **name** (string) - The name of the stack.
- **operations** (array) - An array of stack operation objects.

#### Response Example
```json
{
    "name": "thumbnail",
    "operations": [
        {
            "name": "resize",
            "options": {
                "width": 200,
                "height": 200
            }
        }
    ]
}
```
```

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

### Get JWT Token using API Key

Source: https://rokka.io/documentation/guides/authentication

Obtain a JWT token for authentication by making a request to the `/user/apikeys/token` endpoint with your API Key.

```APIDOC
## POST /user/apikeys/token

### Description
Generates a JWT token using an existing API Key. The token will have the same permissions as the API Key used.

### Method
GET

### Endpoint
`https://api.rokka.io/user/apikeys/token`

### Parameters
#### Headers
- **Api-Key** (string) - Required - Your rokka API key.
- **Api-Version** (integer) - Required - The API version to use (e.g., 1).
- **Content-Type** (string) - Required - Set to `application/json`.

#### Query Parameters
- **expires_in** (integer) - Optional - The token's validity in seconds. Defaults to 86400 (24 hours).

### Request Example
```
curl -H 'Content-Type: application/json' \
 -H 'Api-Version: 1' \
 -H 'Api-Key: myKey' \
 'https://api.rokka.io/user/apikeys/token'
```

### Response
#### Success Response (200)
Returns a JWT token and its payload.

- **token** (string) - The JWT token for authentication.
- **payload** (object) - The decoded JWT payload containing token details.
  - **id** (string) - The unique identifier associated with the token.
  - **exp** (integer) - The expiration timestamp of the token.
  - **expt** (integer) - The remaining time in seconds until expiration.
  - **ips** (array) - An array of IP addresses from which the token is valid (if specified).
  - **rn** (boolean) - Indicates if random nonce is enabled.

#### Response Example
```json
{
   "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6IjdmOTllMjkxLWM0M2ItNDIzMC1hZTAxLWE3NmFmMjg4ZWM5MCIsImV4cCI6MTY1Mjc4MDE5NSwiZXhwdCI6ODY0MDAsImlwcyI6WyIyMTIuNTAuMTAuMTAiXSwicm4iOnRydWV9.EMU8CAiWQk7rLDm6JJ0ol1muj4bvkrqyqpQbXT3hM_g",
   "payload": {
       "id": "7f99e291-c43b-4230-ae01-a76af288ec90",
       "exp": 1652780195,
       "expt": 86400,
       "ips": [
           "212.50.10.10"
       ],
       "rn": true
   }
}
```
```

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

### Getting a BlurHash from a Rendered Image

Source: https://rokka.io/documentation/references/render

Rokka can generate a BlurHash for any rendered image, providing a compact representation for blurry placeholders. This section details how to obtain it.

```APIDOC
## Getting a BlurHash from a Rendered Image

### Description
Obtain a BlurHash for a rendered image, which can be used as a placeholder before the actual image loads. This is done by requesting the `.blur` format of an image.

### Method
GET

### Endpoint
`https://rokka.rokka.io/plain/{hash}.blur`

### Parameters
#### Path Parameters
- **hash** (string) - Required - The hash of the image for which to generate the BlurHash.

### Request Example
```
GET https://rokka.rokka.io/plain/68e13ab4522ccd1084e21b721c2b626f5c2634ef.blur
```

### Response
#### Success Response (200)
- **blurhash** (string) - The BlurHash string for the image.

#### Response Example
```json
{
  "blurhash": "L[JbHoogofbb?wkCRjofxvjroLae"
}
```

### Client-side Usage Example
```html
<script type="module" src="https://unpkg.com/blurhash-img?module"></script>
<blurhash-img 
  hash="L[JbHoogofbb?wkCRjofxvjroLae"
  style="--aspect-ratio: 840/1260; width: 50%">
</blurhash-img>
```
```

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

### Authenticating with a Bearer Token

Source: https://rokka.io/documentation/guides/authentication

This section explains how to use a Bearer token for authentication by including it in the 'Authorization' header of your API requests. It also provides an example using cURL.

```APIDOC
## GET /user/apikeys/current

### Description
Authenticates the current user using a provided Bearer token.

### Method
GET

### Endpoint
`https://api.rokka.io/user/apikeys/current`

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - The authentication token, prefixed with `Bearer `.
- **Content-Type** (string) - Required - Must be `application/json`.
- **Api-Version** (string) - Required - The API version, e.g., `1`.

### Request Example
```bash
curl -H 'Content-Type: application/json' \
 -H 'Api-Version: 1' \
 -H 'Authorization: Bearer $TOKEN' \
 'https://api.rokka.io/user/apikeys/current'
```

### Response
#### Success Response (200)
- **(Response structure not detailed in the provided text)**

#### Response Example
(No example provided in the source text)
```

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

### Upload Image using Rokka CLI

Source: https://rokka.io/documentation/guides/php-client-library-intro

This command uploads a source image to your Rokka organization. Replace `$YOUR_ORG` with your organization name and `rokka-pic.png` with your image file name. The output provides metadata including the image hash.

```bash
rokka sourceimages create $YOUR_ORG rokka-pic.png

```

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

### Example Render URL with Upscaling Control (Rokkka)

Source: https://rokka.io/documentation/guides/best-practices-for-stack-configurations

This Rokkka render URL demonstrates how to enable or disable image upscaling on demand. By including '/v-s-1' in the URL, you instruct the stack to upscale the image to the specified dimensions, even if the source image is smaller. This is useful when precise output dimensions are required.

```text
https://{organization}.rokka.io/{stack-name}/v-w-500-s-1/{hash}.{format}
```

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

### Get Facets for Source Images

Source: https://rokka.io/documentation/references/searching-images

Retrieve facets for user-defined metadata associated with source images. This is useful for categorizing images based on labels or other string-based metadata.

```APIDOC
## GET /sourceimages/{organization_id}

### Description
Retrieves facets for user-defined metadata stored as `String` or `Array with String` for source images within a specific organization. This is useful for obtaining lists of all used labels or other metadata values.

### Method
GET

### Endpoint
`/sourceimages/{organization_id}`

### Query Parameters
- **facets** (string) - Required - A comma-separated list of fields for which to retrieve facets. Example: `user:array:labels`.
- **limit** (integer) - Optional - If set to `0`, only facet counts are returned without the actual source images.

### Request Example
```bash
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?facets=user:array:labels'
```

### Response
#### Success Response (200)
- **total** (integer) - The total number of source images matching the query.
- **items** (array) - An array of source image objects (may be empty if `limit=0`).
- **cursor** (string) - A cursor for pagination.
- **facets** (object) - An object containing facet data for the requested fields.
  - **[facet_field_name]** (array) - An array of facet objects for a specific field.
    - **value** (string) - The value of the facet.
    - **count** (integer) - The number of source images associated with this facet value.

#### Response Example
```json
{
    "total": 1905,
    "items": [
        {
           "...."
        }
    ],
    "cursor": "VaOsN4hoQW9KdzVQKzQ1TzBDUHlSd2NtOWtMV2RzYjJKaGJEUTRPVFF6WkdJMVkyWmlNRE0zTm1WaU4yRTBNVGt3WVdWbE1ESXdPRGN6TWpka05ESTFaalZzYVdsd0xXUmxkbVZzYjNCdFpXNTAB",
    "facets": {
        "user:array:labels": [
            {
                "value": "mountain",
                "count": 4
            },
            {
                "value": "lake",
                "count": 3
            },
            {
                "value": "river",
                "count": 1
            }
        ]
    }
}
```
```

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

### JavaScript Library Token Handling

Source: https://rokka.io/documentation/guides/authentication

Explains how to integrate token management into the Rokka.io JavaScript library, including callbacks for getting and setting tokens, and configuring token options.

```APIDOC
## JavaScript Library Token Management

### Description
This section outlines the integration of JWT tokens with the Rokka.io JavaScript library. It requires defining callback functions for retrieving and storing tokens, typically using browser storage like `localStorage`. Token options for generation can also be configured.

### Token Storage Callbacks
```javascript
const getToken = () => {
   return window.localStorage.getItem('rokka-token');
}

const setToken = (token) => {
   window.localStorage.setItem('rokka-token', token ?? '');
}
```

### Initializing the Rokka Client with Token Callbacks and Options
```javascript
import rokka from '@rokka/api-client';

const rka = rokka({
   apiTokenGetCallback: getToken,
   apiTokenSetCallback: setToken,
   apiTokenOptions: {
       expires_in: 3600 * 72, // Token valid for 3 days
       renewable: true,
       no_ip_protection: false,
       ips: 'request_ip' // Example: IP protection enabled, allowing current IP
   }
});
```

### Token Options Explained
- **`expires_in`** (number): Sets the token's expiration time in seconds. Default is 86400 (1 day).
- **`renewable`** (boolean): Determines if the token can be renewed. Defaults to `true` if IP protected, `false` otherwise. Can be explicitly set.
- **`no_ip_protection`** (boolean): If `true`, disables IP protection. Defaults to `false`.
- **`ips`** (string): Defines allowed IP addresses or networks. Use `request_ip` to include the current IP. Can be a comma-separated list (max 10 values, up to 10,000 addresses).

*Note: The JavaScript library attempts to auto-refresh tokens if they are still valid.*
```

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

### Create a Rokka Stack with Resize and Rotate Operations (cURL)

Source: https://rokka.io/documentation/references/stacks

This snippet demonstrates how to create a new Rokka stack with specific image manipulation operations (resize and rotate) and JPG quality settings using a cURL request. It requires the Content-Type header to be application/json and uses the PUT method to the stacks endpoint.

```bash
curl -H 'Content-Type: application/json' -X PUT 'https://api.rokka.io/stacks/testorganization/teststack' -d '{
    "description" : "This stack does resize and rotate",
    "operations":
    [
        {
            "name": "resize",
            "options": {
                "width": 200,
                "height": 200
            }
        },
        {
            "name": "rotate",
            "options": {
                "angle": 45
            }
        }
    ],
    "options": {
        "jpg.quality": 60
    }
}'

```

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

### Configure Stack for Original Source File Delivery (JSON)

Source: https://rokka.io/documentation/references/stacks

This configuration creates a rokka.io stack that delivers the original uploaded file without any modifications or optimizations. It requires an empty operations collection and the `source_file: true` option. This configuration cannot include any other stack operations or options.

```json
{
    "operations": [],
    "options": {
        "source_file": true
    }
}
```

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

### Get User Information

Source: https://rokka.io/documentation/references/users-and-memberships

Retrieves general user information, including user IDs. This command can be used to obtain the user ID needed for removing a user from an organization.

```bash
curl -X GET 'https://api.rokka.io/user' -H "Content-Type: application/json"
```

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

### Signing an Actual URL

Source: https://rokka.io/documentation/references/protected-images-and-stacks

Demonstrates how to sign a URL using your signing key. This is useful for generating secure, direct links to your rokka.io hosted assets. It's recommended to use the provided client libraries for production environments.

```APIDOC
## POST /utils/test/sign_url

### Description
Signs a given URL. This endpoint is primarily for testing and demonstration purposes. For production, it is recommended to use the client libraries and keep your signing key secure.

### Method
POST

### Endpoint
`/utils/test/sign_url`

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to be signed.

### Request Example
```bash
curl --request POST 'http://api.rokka.io/utils/test/sign_url' \
    --form 'url=https://mycompany.rokka.io/somestack/hash.jpg'
```

### Response
#### Success Response (200)
- **signed_url** (string) - The signed URL.

#### Response Example
```json
{
  "signed_url": "https://mycompany.rokka.io/somestack/hash.jpg?sig=generated_signature"
}
```

## Signing a URL with Bash (for demonstration)

### Description
An example of how to manually sign a URL using bash, `sha256sum`, and your signing key. This method is not recommended for production use.

### Method
N/A (Manual Bash Script)

### Endpoint
N/A

### Request Example
```bash
URLPATH=/somestack/hash.jpg
KEY=your_signing_key_here # Replace with your actual signing key
SIGNATURE=$(echo -n "${URLPATH}:${KEY}" | sha256sum | cut -c 1-16)
echo "https://mycompany.rokka.io/${URLPATH}?sig=${SIGNATURE}"
```
```

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

### Get Current User API Key Info

Source: https://rokka.io/documentation/references/users-and-memberships

Retrieves information about the currently active API key for the user. This is useful if the API key ID is not readily available.

```bash
curl -X GET "https://api.rokka.io/user/apikeys/current" -H "Content-Type: application/json"
```

```php
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
echo $client->getCurrentUserApiKey()->getId();
```

```javascript
console.log((await rokka.user.getCurrentApiKey()).body)
```

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

### Flexible Resize and Crop with Stack Variables (Rokkka Configuration)

Source: https://rokka.io/documentation/guides/best-practices-for-stack-configurations

This configuration defines operations for resizing and cropping images using variables. It allows dynamic control over image dimensions through URL parameters, making image rendering more flexible. The 'variables' section defines how to calculate the final width and height based on user-provided parameters like 'w' (width) and 'h' (height).

```json
{
  "operations": [
    {
      "name": "resize",
      "options": {
        "mode": "fill"
      },
      "expressions": {
        "width": "$finalWidth",
        "height": "$finalHeight"
      }
    },
    {
      "name": "crop",
      "options": {},
      "expressions": {
        "width": "$finalWidth",
        "height": "$finalHeight"
      }
    }
  ],
  "options": {
    "autoformat": true
  },
  "variables": {
    "defaultWidth": 900,
    "defaultHeight": 600,
    "w": 0,
    "h": 0,
    "r": "$defaultWidth / $defaultHeight",
    "finalWidth": "$w == 0 ? ($h == 0 ? $defaultWidth : ($h * $r)) : $w",
    "finalHeight": "$h == 0 ? $finalWidth / $r : $h"
  }
}
```

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

### Get Traffic and Storage Stats for Your Organization

Source: https://rokka.io/documentation/references/stats

Retrieves statistics for your organization over the past 30 days, including the current day. Requires an API key and the organization identifier.

```APIDOC
## GET /stats/{organization}

### Description
Retrieves traffic and storage statistics for a specified organization over the past 30 days, including today.

### Method
GET

### Endpoint
`/stats/{organization}`

### Parameters
#### Path Parameters
- **organization** (string) - Required - The identifier of the organization for which to retrieve stats.

#### Query Parameters
None

### Request Example
```bash
curl -H "Api-Key: $API_KEY" -X GET "https://api.rokka.io/stats/{organization}"
```

### Response
#### Success Response (200)
- **data** (object) - Contains the statistics for the organization.
  - **traffic** (object) - Traffic statistics.
    - **used** (integer) - Amount of traffic used.
    - **limit** (integer) - Traffic limit.
  - **storage** (object) - Storage statistics.
    - **used** (integer) - Amount of storage used.
    - **limit** (integer) - Storage limit.

#### Response Example
```json
{
  "data": {
    "traffic": {
      "used": 1024000000,
      "limit": 2048000000
    },
    "storage": {
      "used": 5368709120,
      "limit": 10737418240
    }
  }
}
```
```

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

### Read Organization Data using cURL

Source: https://rokka.io/documentation/references/organizations

This snippet demonstrates how to retrieve the data of a specific organization using a GET request to the rokka API. It requires the websafe name of the organization in the URL.

```bash
curl -X GET 'https://api.rokka.io/organizations/awesomecompany'

```

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

### Prefix Filtering by Image Name (curl)

Source: https://rokka.io/documentation/references/searching-images

Filters images by their name, returning only those that start with a specified prefix. This is done by appending the 'name' parameter followed by the prefix and a wildcard character '*'.

```curl
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?name=plan*'
```

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

### Getting the Signing Key

Source: https://rokka.io/documentation/references/protected-images-and-stacks

This section explains how to retrieve the signing key for your organization. Currently, new keys cannot be created or deleted via the API, but support is available upon request.

```APIDOC
## GET /organizations/{organization}/signing_keys

### Description
Retrieves the signing keys associated with a specific organization. This endpoint is primarily for informational purposes as key creation and deletion are not yet supported.

### Method
GET

### Endpoint
`/organizations/mycompany` (Example path, replace `mycompany` with your organization ID)

### Parameters
#### Path Parameters
- **organization** (string) - Required - The identifier of the organization for which to retrieve signing keys.

### Request Example
```bash
KEY=$(curl --request GET 'http://api.rokka.io/organizations/mycompany' | \
jq .signing_keys[0].key)
echo $KEY
```

### Response
#### Success Response (200)
- **signing_keys** (array) - An array of signing key objects.
  - **key** (string) - The actual signing key.

#### Response Example
```json
{
  "signing_keys": [
    {
      "key": "your_signing_key_here"
    }
  ]
}
```
```

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

### Configure Stack Options for Remote Images

Source: https://rokka.io/documentation/references/stacks

Set remote image fetching options on a per-stack basis. This allows for different remote image configurations for different stacks within the same organization.

```APIDOC
## PUT /stacks/{organization_id}/{stack_name}

### Description
Updates a specific stack configuration, including its options for remote image fetching.

### Method
PUT

### Endpoint
`/stacks/{organization_id}/{stack_name}`

### Parameters
#### Path Parameters
- **organization_id** (string) - Required - The ID of the organization.
- **stack_name** (string) - Required - The name of the stack to update.

#### Request Body
- **operations** (array) - Optional - An array of image manipulation operations for the stack.
- **options** (object) - Optional - Configuration options for the stack.
  - **remote_fullurl_allow** (boolean) - Optional - If true, allows fetching images from any public URL for this stack.
  - **remote_fullurl_whitelist** (array of strings) - Optional - An array of regex patterns to restrict allowed domains when `remote_fullurl_allow` is true for this stack.
  - **remote_basepath** (string) - Optional - The base URL path for remote images for this stack.

### Request Example
```json
{
  "operations": [
    {
      "name": "resize",
      "options": {
        "width": 200
      }
    }
  ],
  "options": {
    "remote_fullurl_allow": true,
    "remote_fullurl_whitelist": ["\.rokka\.io"]
  }
}
```

```json
{
  "operations": [
    {
      "name": "resize",
      "options": {
        "width": 200
      }
    }
  ],
  "options": {
    "remote_basepath": "https://blog.liip.ch/content/uploads/"
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Stack updated successfully."
}
```
```

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

### Configure Stack Operation Options with Expressions (JSON)

Source: https://rokka.io/documentation/references/stacks

This JSON configuration demonstrates how to use expressions to set dynamic options for stack operations like resize and crop. It allows for values to be defined via stack variables and overridden in render URLs. Expressions in 'expressions' property take precedence over 'options'.

```json
{
  "operations": [
    {
      "name": "resize",
      "options": {
        "mode": "fill"
      },
      "expressions": {
        "width": "$w",
        "height": "$h"
      }
    },
    {
      "name": "crop",
      "expressions": {
        "width": "$w",
        "height": "$h"
      }
    }
  ],
  "variables": {
    "w": 500,
    "h": "$w / 2"
  }
}
```

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

### Sort Images by Multiple Fields (curl)

Source: https://rokka.io/documentation/references/searching-images

Sorts images by multiple criteria. This example first sorts by creation date in descending order and then by size in ascending order for images with the same creation date.

```curl
curl -H 'Content-Type: application/json' -X GET 'https://api.rokka.io/sourceimages/myorganization?sort=created desc,size asc'
```

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

### Get Signing Key - Bash, PHP, JavaScript

Source: https://rokka.io/documentation/references/protected-images-and-stacks

Retrieves the signing key for an organization. This key is essential for signing URLs. Currently, key creation and deletion are not supported via the API.

```bash
KEY=$(curl --request GET 'http://api.rokka.io/organizations/mycompany' | 
jq .signing_keys[0].key)
echo $KEY

```

```php
$client = \Rokka\Client\Factory::getUserClient('awesomecompany', 'apiKey');
$key = $client->getOrganization()->getSigningKeys()[0];

```

```javascript
var rokka = require('rokka')({apiKey: 'apiKey'})
var key = await rokka.organizations.get('test')).body.signing_keys[0].key

```
Tokens:
Raw