> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engini.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API walkthrough (cURL)

> Zero to executed tool using nothing but HTTP - discovery, an OAuth connection, defaults, and execution.

Everything the SDKs and CLI do is plain HTTP underneath. This walkthrough drives the full journey with cURL only.

```bash theme={null}
export ENGINI_API_KEY=eng_...
BASE=https://api.engini.io/v1
AUTH="x-api-key: $ENGINI_API_KEY"
```

## 1. Verify the credential

```bash theme={null}
curl -s "$BASE/auth/whoami" -H "$AUTH"
```

## 2. Discover applications

```bash theme={null}
curl -s "$BASE/applications?available=true&top=20" -H "$AUTH" | jq '.items[].slug'
```

Read one application's detail - this is where you learn **how it connects** (`authenticationMethods`, each with an `authenticationId` and field list) and whether it supports object selection:

```bash theme={null}
curl -s "$BASE/applications/outlook" -H "$AUTH" \
  | jq '.authenticationMethods[] | {authenticationId, authenticationName, requiresOAuthSignIn}'
```

## 3. Create a connection

**Direct credentials** (API-key/DB style methods) - one call:

```bash theme={null}
curl -s -X POST "$BASE/connections" -H "$AUTH" -H "Content-Type: application/json" -d '{
  "applicationSlug": "slack",
  "connectionName": "Sales workspace",
  "authenticationId": 2,
  "fields": { "token": "xoxb-..." }
}'
```

**OAuth methods** (`requiresOAuthSignIn: true`) - three steps:

```bash theme={null}
# a. get the sign-in URL + state
curl -s -X POST "$BASE/connections/GetSignInUrl" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"applicationSlug": "outlook", "authenticationId": 0}'
# -> { "signInUrl": "...", "state": "<guid>" }

# b. the user authorizes in a browser at signInUrl; poll until the token lands
curl -s "$BASE/connections/AccessToken/<state>" -H "$AUTH"
# -> null body while pending (keep polling); then { "status": "completed", "connectionData": {...} }

# c. create the connection from connectionData's key/values
curl -s -X POST "$BASE/connections" -H "$AUTH" -H "Content-Type: application/json" -d '{
  "applicationSlug": "outlook",
  "connectionName": "My Outlook",
  "authenticationId": 0,
  "fields": { "...": "values from connectionData" }
}'
```

Optionally make it your default for the app (what implicit execution resolves to):

```bash theme={null}
curl -s -X PUT "$BASE/connections/42/Default" -H "$AUTH"
```

## 4. Discover tools and read a contract

```bash theme={null}
curl -s "$BASE/tools?applicationSlug=outlook&top=10" -H "$AUTH" | jq '.items[].toolSlug'
curl -s "$BASE/tools/outlook_send_mail" -H "$AUTH" | jq '{inputSchema, supportsFilters, supportsTopOffset}'
```

## 5. Execute

```bash theme={null}
curl -s -X POST "$BASE/tools/outlook_send_mail/execute?connectionId=42" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{ "fields": { "to": "alex@acme.com", "subject": "Hi", "body": "From the Engini API." } }'
```

```json theme={null}
{ "isSuccess": true, "output": { ... }, "historyId": 12345, "executionInfo": { ... } }
```

<Warning>
  Branch on `isSuccess` - a tool-runtime failure returns HTTP `200` with `isSuccess: false` and an `errorMessage`. Every non-200 uses the standard [error envelope](/concepts/pagination-and-errors); on `429` honor `Retry-After`.
</Warning>

Omit `?connectionId=` to use your default connection; pass `?toolsetId=` to scope resolution to a [toolset](/sdk/toolsets). Full semantics: [API overview](/api-reference/overview).