Getting Started

From an API credential to your first authenticated request against the Emofy Platform API.

This guide takes you from zero to your first successful API call. It should take about five minutes.

1. Get an API credential

API credentials are created in the Developer Portal, under your organization's settings. Each credential is:

scoped to one organization — it authenticates as your whole org, so keep it server-side and never ship it in client code;
scoped to specific permissions — each endpoint requires scopes such as tasks:read or tasks:write;
tied to one environment — see Credentials for the per-environment model and rate-limit tiers.

Store the credential in an environment variable:

export EMOFY_API_KEY="sk_live_..."

2. Know the base URL

All routes live under /api, and the partner API is versioned under /api/v1:

https://api.emofy.net/api/v1

See REST API Overview for versioning and the response envelope.

3. Make your first request

You can call the API directly with curl:

curl https://api.emofy.net/api/v1/tasks?limit=5 \
  -H "Authorization: Bearer $EMOFY_API_KEY"

A successful response uses the V1 envelope — your data is in data, pagination and correlation info in meta:

{
  "data": [{ "id": "task_01h...", "title": "..." }],
  "meta": {
    "requestId": "req-...",
    "timestamp": "2026-06-17T12:00:00.000Z",
    "pagination": { "total": 42, "page": 1, "limit": 5, "hasMore": true }
  }
}

4. Or use the SDK

For a typed experience with automatic retries and envelope unwrapping, use the official SDK:

npm install @emofy/dev-sdk

import { createEmofyClient } from "@emofy/dev-sdk";

const client = createEmofyClient({
  apiKey: process.env.EMOFY_API_KEY!,
  baseUrl: "https://api.emofy.net/api/v1",
});

const { data } = await client.tasks.list({ limit: 5 });
console.log(data);