Geo Query

Geo Knowledge Graph — Querying

Query and explore entities, types, properties, and relations in the Geo knowledge graph via its GraphQL API.

When to apply

Use this skill when the user wants to:

• Look up an entity by ID.
• Search for entities of a given type (optionally scoped to a space).
• Explore what properties and relations an entity has.
• Discover the schema for an unfamiliar entity type before publishing.
• Find type, property, or relation type IDs.

API basics

• Endpoint: https://testnet-api.geobrowser.io/graphql
• Method: POST with Content-Type: application/json
• Auth: none required for reads.
• UUIDs: 32-char hex, no dashes (e.g. 4faff0b210cb49958e20109409b8699c).
• Browser links: https://www.geobrowser.io/space/{spaceId}/{entityId}.

Core concepts (compact)

• Entity: a unique node in the graph (person, place, article, etc.). Has an ID, name, description, types, values, and relations.
• Property: a typed attribute on an entity (text, date, boolean, decimal, integer, float, url).
• Relation: a typed edge between two entities. Relations are themselves entities — they can have their own properties.
• Type: a category (Person, Article, …). Types define a schema of default properties that every entity of that type inherits.
• Space: an independent community/topic scope. An entity can live in multiple spaces; each has its own perspective.

Full conceptual details: see reference.md.

List query: entities vs entitiesConnection

There are two list queries with the same top-level args (typeId, spaceId, typeIds, spaceIds, filter, first, offset, orderBy) but different shapes. Choose based on result set size:

| | entities | entitiesConnection | | ------------ | ------------------------------------------------- | ------------------------------------------- | | Return shape | flat array | { nodes, edges, pageInfo, totalCount } | | Pagination | first + offset (capped at offset 1000) | first + cursor (after/before) | | Use when | small, bounded lookups; default for > { const out: Array = []; let cursor: string | null = null;

while (true) { const afterClause = cursor ? after: "${cursor}" : ""; const res = await fetch("https://testnet-api.geobrowser.io/graphql", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: { entitiesConnection(typeId: "${typeId}", spaceId: "${spaceId}", first: 500 ${afterClause}) { nodes { id name } pageInfo { hasNextPage endCursor } } }, }), }); const { data } = await res.json(); const conn = data.entitiesConnection; out.push(...(conn?.nodes ?? [])); if (!conn?.pageInfo?.hasNextPage) break; cursor = conn.pageInfo.endCursor; } return out; }

## Filtering

The `filter` arg accepts `EntityFilter` for field-level conditions:

```graphql
{
  entities(typeId: "TYPE_ID", filter: { name: { startsWithInsensitive: "Bitcoin" } }, first: 20) {
    id
    name
  }
}

Common EntityFilter fields:

• id — UUIDFilter (uses is / isNot / in; NOT equalTo).
• name, description, createdAt, updatedAt — StringFilter (startsWithInsensitive, includesInsensitive, equalTo).
• spaceIds, typeIds — UUIDListFilter (anyEqualTo).
• relations, backlinks — EntityToManyRelationFilter (some, none, every).
• values — EntityToManyValueFilter.
• and, or, not.

CRITICAL — scope relation filters by space. Cross-space relation filters can return INTERNAL_SERVER_ERROR on the server. Always include spaceId inside relation filters:

relations: { some: { spaceId: { is: "SPACE_ID" }, toEntity: { ... } } }

Prefer none over every for exclusion. every means "all items must match the full condition" and misbehaves when items have different field values. Use none for "there is no X where Y":

# "entity has no name value"
values: { none: { propertyId: { is: NAME_PROP_ID }, text: { isNull: false } } }

If complex filters return 500s, reduce first from 500 → 100 → 50.

Schema discovery workflow

When you need to publish or understand an entity type you haven't seen before, inspect an existing entity of that type to learn the schema. Do this before assuming any property/relation IDs.

1. Find entities of the type (search by typeId).
2. Pick one and fetch it fully (all values + relations).
3. Read the property names and relation types from the result.
4. Note the IDs — property IDs, relation type IDs, and toEntity IDs for classification values.

{
  entities(typeId: "86db141cf7cb471194ed39088926adb8", first: 3) {
    id
    name
    types {
      id
      name
    }
    values(first: 50) {
      nodes {
        property {
          id
          name
        }
        text
        date
      }
    }
    relations(first: 50) {
      nodes {
        type {
          id
          name
        }
        toEntity {
          id
          name
        }
      }
    }
  }
}

See examples/discover-schema.md for an end-to-end walkthrough.

Finding type and property IDs by name

Type and Property are themselves types — you can query all of them:

# All type definitions
{
  entities(
    typeId: "e7d737c536764c609fa16aa64a8c90ad"
    filter: { name: { includesInsensitive: "article" } }
    first: 20
  ) {
    id
    name
  }
}

# All property definitions
{
  entities(
    typeId: "808a04ceb21c4d888ad12e240613e5ca"
    filter: { name: { includesInsensitive: "date" } }
    first: 20
  ) {
    id
    name
  }
}

For relation types, inspect an entity that uses them — the type { id name } field on a relation gives you the ID.

Well-known IDs

Prefer the SDK's exported constants where possible:

import { SystemIds, ContentIds } from "@geoprotocol/geo-sdk";

(SystemIds.PERSON_TYPE, SystemIds.COMPANY_TYPE, SystemIds.PROJECT_TYPE, SystemIds.EVENT_TYPE);
(ContentIds.ARTICLE_TYPE, ContentIds.TALK_TYPE, ContentIds.PODCAST_TYPE, ContentIds.TOPIC_TYPE);

Common raw IDs (for GraphQL queries):

| Name | ID | | --------------- | ---------------------------------- | | Type (meta) | e7d737c536764c609fa16aa64a8c90ad | | Property (meta) | 808a04ceb21c4d888ad12e240613e5ca | | Person | 4faff0b210cb49958e20109409b8699c | | Article | a2a5ed0cacef46b1835de457956ce915 | | Topic | 5ef5a5860f274d8e8f6c59ae5b3e89e2 |

Well-known space IDs and additional type IDs live in reference.md.

curl sanity check

curl -s --compressed 'https://testnet-api.geobrowser.io/graphql' \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ entities(typeId: \"4faff0b210cb49958e20109409b8699c\", first: 5) { id name } }"}' | jq .

Critical gotchas — quick reference

1. Offset cap 1000 on entities/relations/values — use *Connection + cursor for larger sets.
2. entities is flat, not { nodes { ... } }.
3. typeId/spaceId are top-level args, not inside filter.
4. Scope relation filters by spaceId to avoid INTERNAL_SERVER_ERROR.
5. UUIDFilter uses is / isNot / in, not equalTo. UUIDListFilter uses anyEqualTo.
6. Prefer none over every for exclusion logic.
7. Values come back as typed fields (text, date, boolean, …), not a single value.
8. Relation id ≠ entityId — id is the edge (for deletion); entityId is the relation-as-entity (for relation properties).

More

• reference.md — full filter spec, all well-known IDs, advanced patterns.
• examples/lookup-entity.md — walk through a single-entity fetch and what the shape looks like.
• examples/paginate-list.md — cursor pagination example with totalCount.
• examples/discover-schema.md — the schema-discovery workflow in practice.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: geobrowser
• Source: geobrowser/geo-skills
• License: MIT

Install and usage instructions live in the source repository linked above.