# Elements

`GET | POST | PATCH | DELETE /v1/elements` — Your reusable references: places, props and styles.

- Base URL: https://eroq.ai/v1
- Auth: `Authorization: Bearer eroq_sk_…` (create keys at https://eroq.ai/dashboard/keys)
- Credits: Free

Elements are reusable prompt references (up to 50 per account): a place, a prop or a visual style with a description the prompt-engineering layer folds into any render, and optional reference photos. Characters are referenced as `char:<id>` in `elements` arrays — they live on their own endpoints in the studio.

`POST /v1/elements` creates one (`kind` location|object|style, `name`, `description`, optional `imageUrl`); `GET /v1/elements/{id}` fetches one with its reference-photo pool and its `sheetUrl`; `PATCH /v1/elements/{id}` updates it; `DELETE /v1/elements/{id}` removes it. Pass their ids in the `elements` array of chat, image and video generations. **A `location` or `object` you want to render must carry an accepted look sheet** (see /v1/sheets) — a `style` is description-only and never sheeted.

## Operations

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | `/v1/elements` | List your elements (places, props, styles — each with its `sheetUrl`). |
| `POST` | `/v1/elements` | Create an element. |
| `GET` | `/v1/elements/{id}` | One element with its reference-photo pool and sheet. |
| `PATCH` | `/v1/elements/{id}` | Update name, description or photo. |
| `DELETE` | `/v1/elements/{id}` | Remove an element — past renders are untouched. |

## GET /v1/elements

List your elements (places, props, styles — each with its `sheetUrl`).

### Example request

```bash
curl https://eroq.ai/v1/elements \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/elements', {
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.get("https://eroq.ai/v1/elements", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://eroq.ai/v1/elements", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{
  "elements": [{
    "id": "0b6c…", "kind": "location", "name": "Rooftop bar",
    "description": "rooftop cocktail bar at dusk, string lights", "imageUrl": "", "sheetUrl": ""
  }]
}
```

## POST /v1/elements

Create an element.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kind` | string | yes | `location`, `object` or `style`. |
| `name` | string | yes | Display name, up to 60 characters — what @-mentions match. |
| `description` | string | no | The prompt fragment folded into renders, up to 600 characters. |
| `imageUrl` | string | no | Optional reference photo URL — joins the engine references and the sheet pool. |

### Example request

```bash
curl https://eroq.ai/v1/elements \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "location",
  "name": "Rooftop bar",
  "description": "rooftop cocktail bar at dusk, string lights, skyline behind"
}'
```

```javascript
const res = await fetch('https://eroq.ai/v1/elements', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kind": "location",
    "name": "Rooftop bar",
    "description": "rooftop cocktail bar at dusk, string lights, skyline behind"
  }),
})
console.log(await res.json())
```

```python
import os, requests

res = requests.post(
    "https://eroq.ai/v1/elements",
    headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"},
    json={
        "kind": "location",
        "name": "Rooftop bar",
        "description": "rooftop cocktail bar at dusk, string lights, skyline behind"
    },
)
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "kind": "location",
  "name": "Rooftop bar",
  "description": "rooftop cocktail bar at dusk, string lights, skyline behind"
}`)

	req, _ := http.NewRequest("POST", "https://eroq.ai/v1/elements", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{
  "elements": [{
    "id": "0b6c…", "kind": "location", "name": "Rooftop bar",
    "description": "rooftop cocktail bar at dusk, string lights", "imageUrl": "", "sheetUrl": ""
  }]
}
```

## GET /v1/elements/{id}

One element with its reference-photo pool and sheet.

### Example request

```bash
curl https://eroq.ai/v1/elements/ELEMENT_ID \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/elements/ELEMENT_ID', {
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.get("https://eroq.ai/v1/elements/ELEMENT_ID", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://eroq.ai/v1/elements/ELEMENT_ID", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{
  "elements": [{
    "id": "0b6c…", "kind": "location", "name": "Rooftop bar",
    "description": "rooftop cocktail bar at dusk, string lights", "imageUrl": "", "sheetUrl": ""
  }]
}
```

## PATCH /v1/elements/{id}

Update name, description or photo.

### Example request

```bash
curl -X PATCH https://eroq.ai/v1/elements/ELEMENT_ID \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "rooftop bar at dawn, soft light"
}'
```

```javascript
const res = await fetch('https://eroq.ai/v1/elements/ELEMENT_ID', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.EROQ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "description": "rooftop bar at dawn, soft light"
  }),
})
console.log(await res.json())
```

```python
import os, requests

res = requests.patch(
    "https://eroq.ai/v1/elements/ELEMENT_ID",
    headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"},
    json={
        "description": "rooftop bar at dawn, soft light"
    },
)
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "description": "rooftop bar at dawn, soft light"
}`)

	req, _ := http.NewRequest("PATCH", "https://eroq.ai/v1/elements/ELEMENT_ID", body)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{
  "elements": [{
    "id": "0b6c…", "kind": "location", "name": "Rooftop bar",
    "description": "rooftop cocktail bar at dusk, string lights", "imageUrl": "", "sheetUrl": ""
  }]
}
```

## DELETE /v1/elements/{id}

Remove an element — past renders are untouched.

### Example request

```bash
curl -X DELETE https://eroq.ai/v1/elements/ELEMENT_ID \
  -H "Authorization: Bearer $EROQ_API_KEY"
```

```javascript
const res = await fetch('https://eroq.ai/v1/elements/ELEMENT_ID', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EROQ_API_KEY}` },
})
console.log(await res.json())
```

```python
import os, requests

res = requests.delete("https://eroq.ai/v1/elements/ELEMENT_ID", headers={"Authorization": f"Bearer {os.environ['EROQ_API_KEY']}"})
print(res.json())
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("DELETE", "https://eroq.ai/v1/elements/ELEMENT_ID", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("EROQ_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}
```

### Response


```json
{
  "elements": [{
    "id": "0b6c…", "kind": "location", "name": "Rooftop bar",
    "description": "rooftop cocktail bar at dusk, string lights", "imageUrl": "", "sheetUrl": ""
  }]
}
```

---
Canonical: https://eroq.ai/docs/elements · Index for agents: https://eroq.ai/llms.txt · OpenAPI: https://eroq.ai/openapi.json