Introduction

Ouruka is a cloud-native REST API service for generating unique, structured IDs. It is designed for developers and system integrators who need reliably unique identifiers in their applications — without having to implement counter logic, date stamps, or uniqueness guarantees themselves.

Typical Use Cases

• Product Information Systems (PIM): Consistent article and product numbers across multiple sales channels.
• ERP Systems: Document numbers, order numbers, and delivery note numbers in a uniform format.
• Webshops & E-Commerce: Order numbers, customer numbers, and transaction IDs.
• Logistics: Shipment numbers, pallet IDs, and shipping labels.
• Healthcare: Patient record numbers, sample IDs, and case numbers.
• Manufacturing: Serial numbers, batch designations, and quality IDs.

Ouruka runs in production at ouruka.com and is reachable from anywhere. The complete API documentation with interactive testing is available at ouruka.com/swagger/.

Quick Start

Three steps to your first generated ID:

1. Choose a plan & register

   Select a plan (Discovery, Solar, Galaxy, or Universe) and complete registration. The system automatically creates your personal tenant — your isolated workspace within the Ouruka system — and issues you an api_key exactly once.

   Store your API key securely — it is issued only once and is required for all subsequent API calls.

2. Create a schema

   A schema defines the format of your IDs. You specify which building blocks — date, counter, fixed characters, variables — make up an ID.

   HTTP Request

   POST /v2/schema
   X-API-KEY: <your API key>
   
   {
     "name":    "order-number",
     "pattern": "ORD-{DATE:YYYY}{DATE:MM}-{COUNTER:5}"
   }

   This pattern generates IDs like ORD-202503-00001.

3. Generate an ID

   Using the schema name, request the next ID. Ouruka ensures every generated ID is unique — even under concurrent requests.

   HTTP Request

   POST /v2/id/generate
   X-API-KEY: <your API key>
   
   {
     "schema": "order-number"
   }

   Response 200 OK

   {
     "id": "ORD-202503-00042"
   }

Authentication

All endpoints that read or write data require a valid API key. It is transmitted as an HTTP header:

X-API-KEY: <your API key>

The API key is automatically issued by the system upon registration. It uniquely identifies your tenant and controls access to all your schemas, counters, and ID histories.

ID Generation with Schemas

Schemas are the core of Ouruka. They define the exact format of an ID through a pattern — a string where fixed text elements are combined with dynamic placeholders.

ART-{DATE:YY}{DATE:MM}-{COUNTER:4}
      ↓
ART-2503-0017

{VAR1}      — value inserted directly
{VAR1:-}    — value with hyphen as separator
{VAR2:/}    — value with slash as separator

Random IDs (UID)

In addition to structured schema IDs, Ouruka offers random-based unique identifiers. UIDs contain no semantic information like dates or counters — they are purely unique and suited for tokens, API keys, and any scenario where anonymity and randomness are required.

POST /v2/uid/numeric

POST /v2/uid/alpha

String Conversion (Keyify)

POST /v2/keyify

Keyify converts arbitrary free-text strings into URL-safe, uniformly formatted keys. Typical use cases include URL slugs, database keys, technical identifiers, or SEO-friendly product URLs generated from natural language input.

Transformations

• Spaces are replaced with hyphens (-)
• Special characters are removed or converted
• Casing is unified (lowercase)
• German umlauts are transliterated: ä→ae, ö→oe, ü→ue, ß→ss
• Consecutive hyphens are cleaned up

Umlaut Reference

Examples

History

Ouruka logs every generated ID in a history list that is retrievable per schema. Stored data includes the generated ID, the timestamp (UTC), and optional metadata.

The history allows you to trace which IDs were generated and when — useful for audits, error analysis, and workflows that check for completeness.

GET /v2/history
X-API-KEY: <your API key>

Retention Period by Plan

FAQ

Swagger / API Reference

The complete technical API documentation is available interactively through the Swagger UI — directly in the browser, no external tools needed.

• Complete endpoint overview: All available API endpoints with methods, paths, and descriptions.
• Request & response schemas: Exact definitions of all input and output fields, data types, and required fields.
• Interactive testing: Call endpoints directly in the browser with your own API key.
• Example requests & responses: Concrete examples for typical use cases.
• Error codes: Documentation of all HTTP error codes and their meaning.

To use the Swagger UI, click Authorize and enter your X-API-KEY.