Skip to main content
GET
/
v1
/
entities
/
byId
Get Entity by ID
curl --request GET \
  --url https://api.shoal.xyz/v1/entities/byId \
  --header 'Authorization: Bearer <token>'
Returns the canonical entity record for one Shoal entity id.

​
Query Parameters

  • id (integer, required)

​
Request

cURL
curl -X GET "https://api.shoal.xyz/v1/entities/byId?id=23151" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response (200)

{
  "data": {
    "id": 23151,
    "canonicalName": "Ethereum",
    "displayName": "Ethereum",
    "entityType": "project",
    "status": "active",
    "aliases": ["Ethereum Foundation", "ETH"],
    "references": []
  }
}

​
Notes

  • This is the canonical entity detail surface.
  • It is designed to become the anchor for references, relationships, timeline, research, and media traversal.
  • references is now backed by dedicated storage, even if the current dataset for a given entity is still sparse.

​
Errors

  • 400 if id is missing
  • 404 if the entity does not exist
  • 500 on internal server error