Quickstart: create your first entity

Everything in Legion hangs off an entity: a device, a sensor, a track — anything with an identity. Registering one is the prerequisite for locations, video streams, tasking, and events. This page creates a camera entity and proves it exists.

Before you start: a token and your organization_id from Quickstart: authenticate.

1. Create the entity.

   POST /v3/entities with both headers. Four fields are required: name, category, type, and status.

   curl

   curl -s -X POST "https://api.usg.legion.picogrid.com/v3/entities" \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-ORG-ID: $ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Walkthrough Camera",
       "category": "DEVICE",
       "type": "Camera",
       "status": "active",
       "affiliation": "FRIEND",
       "is_active": true,
       "metadata": { "source": "quickstart" }
     }'

   Python

   resp = requests.post(
       f"{API}/v3/entities",
       headers={"Authorization": f"Bearer {token}", "X-ORG-ID": org_id},
       json={
           "name": "Walkthrough Camera",
           "category": "DEVICE",
           "type": "Camera",
           "status": "active",
           "affiliation": "FRIEND",
           "is_active": True,
           "metadata": {"source": "quickstart"},
       },
       timeout=30,
   )
   resp.raise_for_status()   # a validation error raises here, not as a KeyError below
   entity = resp.json()
   entity_id = entity["id"]

   The response is the stored entity. The fields to keep:

   {
     "id": "7f3d2a10-5b6c-4e8f-9a01-23d4e5f6a7b8",
     "organization_id": "2b1c9f04-8f6e-4c1a-9a67-1d2f3e4a5b6c",
     "name": "Walkthrough Camera",
     "category": "DEVICE",
     "type": "Camera",
     "status": "active",
     "affiliation": "FRIEND",
     "is_active": true,
     "created_at": "2026-08-13T18:40:12.114Z",
     "updated_at": "2026-08-13T18:40:12.114Z"
   }

   id is the handle every later call uses. created_at is permanent: it is the entity’s registration timestamp for as long as the record exists.

2. Read it back.

   curl

   curl -s "https://api.usg.legion.picogrid.com/v3/entities/$ENTITY_ID" \
     -H "Authorization: Bearer $TOKEN" -H "X-ORG-ID: $ORG_ID"

   Python

   resp = requests.get(
       f"{API}/v3/entities/{entity_id}",
       headers={"Authorization": f"Bearer {token}", "X-ORG-ID": org_id},
       timeout=30,
   )
   resp.raise_for_status()
   print(resp.json()["name"])   # "Walkthrough Camera"

   Getting your entity back with the same id proves the write landed. It is also visible to everyone in your organization from here on — entities are org-scoped, which is why the X-ORG-ID header is mandatory on both calls.

3. Find it by search.

   The list view of the same data, and the query the Orion map itself uses:

   curl

   curl -s -X POST "https://api.usg.legion.picogrid.com/v3/entities/search?limit=10" \
     -H "Authorization: Bearer $TOKEN" -H "X-ORG-ID: $ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{ "filters": { "category": ["DEVICE"], "types": ["Camera"] } }'

   Python

   resp = requests.post(
       f"{API}/v3/entities/search",
       params={"limit": 10},
       headers={"Authorization": f"Bearer {token}", "X-ORG-ID": org_id},
       json={"filters": {"category": ["DEVICE"], "types": ["Camera"]}},
       timeout=30,
   )
   resp.raise_for_status()
   for e in resp.json()["results"]:
       print(e["id"], e["name"])

   Your camera appears in results. Filters combine: category, types, status, name, affiliation.

Choosing category and type

category is the coarse bucket (DEVICE for hardware). type is free-form but conventional — Camera, Terminal, Drone — and search filters match it exactly, so pick a consistent spelling and keep it.

Troubleshooting

Response	Cause	Fix
400 Organization ID is required	Missing X-ORG-ID	Add the header on every entity call.
400 validation error	One of the four required fields missing	name, category, type, status are all mandatory.
403	Your role in this org cannot create entities	Check your role in step 2 of the auth quickstart (organization_role).

Next steps

• Attach a location and video stream — put this entity on the map and give it a live feed.
• Entities API reference — every field, including parent_id, expires_at, and classification.