hyperindex

name	hyperindex
description	Query the Hypercerts Hyperindex GraphQL indexer for ATProto hypercert records. Use when consumers need GraphQL queries, filters, pagination, sorting, or workflows for org.hypercerts.* and app.certified.* records on api.indexer.hypercerts.dev or dev.api.indexer.hypercerts.dev.
compatibility	Requires network access to the Hyperindex GraphQL endpoint. Examples target the current ATProto Hypercerts schema exposed by api.indexer.hypercerts.dev/graphql.
allowed-tools	bash read fetch_content
metadata	{"product":"Hyperindex","production_endpoint":"https://api.indexer.hypercerts.dev/graphql","staging_endpoint":"https://dev.api.indexer.hypercerts.dev/graphql"}

Hyperindex Queries

Use this skill when helping consumers read Hypercerts records from the hosted Hyperindex GraphQL API.

The current production indexer is ATProto-first. Do not explain it using old Hyperindex concepts such as generic attestations or older claim models unless the live schema exposes them. Base generated queries on the live schema and the current typed production collections:

• app.certified.actor.organization
• app.certified.actor.profile
• app.certified.badge.award
• app.certified.badge.definition
• app.certified.badge.response
• app.certified.graph.follow
• app.certified.link.evm
• app.certified.location
• org.hypercerts.claim.activity
• org.hypercerts.claim.contribution
• org.hypercerts.claim.contributorInformation
• org.hypercerts.claim.rights
• org.hypercerts.collection
• org.hypercerts.context.acknowledgement
• org.hypercerts.context.attachment
• org.hypercerts.context.evaluation
• org.hypercerts.context.measurement
• org.hypercerts.funding.receipt
• org.hypercerts.workscope.tag

Endpoints

• Production: https://api.indexer.hypercerts.dev/graphql
• Staging: https://dev.api.indexer.hypercerts.dev/graphql

Use production by default for consumer examples. api.indexer.hypercerts.dev is the production endpoint and currently exposes presence filters and typed queries for the collections above. Staging and production do not always run the same schema, and this skill usually reflects the default branch before every endpoint has caught up. Because ATProto data is network-wide, do not describe staging as a separate dataset unless you have verified an environment-specific indexing difference.

Before answering

1. If the user asks for an exact field, filter, enum, or union and you are not sure, introspect the endpoint first.
2. Prefer schema-specific queries such as orgHypercertsClaimActivity over generic records when the collection has a typed query and the caller only needs schema-valid records.
3. Use generic records(collection: ...) when the caller needs raw JSON, operational debugging, unknown-schema records, or records hidden from typed GraphQL by validation metadata.
4. Use recordTimeline when the caller needs one newest-first feed across multiple collections. It requires where.collection.in, supports optional where.did.in author filtering, and does not expose totalCount.
5. Always include pagination (first, after, pageInfo { hasNextPage endCursor }) in list examples.
6. Keep selection sets small. Add fields only when needed for the workflow.
7. Use inline fragments for union fields such as descriptions, images, attachment content, proof fields, and strong references.
8. Do not assume the target endpoint exposes every feature described in this skill. main may be ahead of staging, and staging may be ahead of production. When a query depends on newer schema features such as recordTimeline, nested filters, author labels, validation metadata, or collection-specific fields, introspect the target endpoint first. If the feature is missing, tell the user which endpoint lacks it and offer the closest fallback, such as search(query: ..., collection: ...) plus client-side filtering.

Detailed schema reference: references/schema-reference.md

GraphQL request shape

curl -s https://api.indexer.hypercerts.dev/graphql \
  -H 'content-type: application/json' \
  --data '{"query":"query { collectionStats { collection count } }"}'

For examples with variables:

{
  "query": "query HypercertsForDid($did: String!) { orgHypercertsClaimActivity(first: 20, where: { did: { eq: $did } }) { edges { node { uri title } } } }",
  "variables": { "did": "did:plc:..." }
}

Record author identity

Generated record types, GenericRecord, RecordTimelineNode, RecordEvent, and typed record subscriptions expose structured author identity metadata:

author {
  did
  handle
}

Prefer author.did and author.handle in output selection sets. author is non-null; handle is nullable when no current verified handle is available. The direct record-level did output remains functional but is deprecated. DID filters are unchanged: continue using where.did to filter records by author DID.

author is reserved record metadata. If an uploaded Lexicon defines a top-level property named author, Hyperindex skips that property and its generated filter in favor of ActorIdentity; tell schema owners to rename colliding Lexicon properties.

Core filter model

Most typed list queries accept:

• where: collection-specific filter object
• first / after: forward pagination
• last / before: backward pagination
• sortBy: collection-specific enum, default is usually indexed_at
• sortDirection: ASC or DESC, default is DESC

Common metadata, scalar, and DID filter operators:

where: { uri: { eq: "at://did:plc:.../org.hypercerts.claim.activity/rkey" } }
where: { uri: { in: ["at://did:plc:.../collection/rkey1", "at://did:plc:.../collection/rkey2"] } }
where: { did: { eq: "did:plc:..." } }
where: { did: { in: ["did:plc:a", "did:plc:b"] } }
where: { title: { contains:   
       
       
       

uri filters are record metadata filters, not JSON-field filters. They support exact lookup with eq and batched lookup with in.

Any single in operator accepts up to 100 values. For larger DID, URI, label source/value, or scalar batches, split the values into multiple GraphQL requests and merge the paginated results client-side. This limit is separate from connection page size.

Complex fields expose isNull for presence checks. Some complex fields use the shared PresenceFilterInput; arrays, refs, and unions can instead expose generated nested filter inputs up to three lexicon path segments deep. Do not rely on the input type name for presence checks; introspect the field and use isNull. Nested scalar leaves support exact operators only: eq, in, and isNull. Multiple predicates inside the same array any must match the same array item. Nested array fields inside an existing any scope expose presence checks only; Hyperindex does not advertise nested any within another any.

where: { image: { isNull: false } }
where: { subjects: { isNull: false } }
where: { contributors: { any: { contributorIdentity: { identity: { eq: "did:plc:..." } } } } }
where: { items: { any: { itemIdentifier: { uri:        

Nested filters do not support substring operators (contains, startsWith), comparison operators (gt, lt, gte, lte), nested-array any filters inside another any, nested sorting, arbitrary JSON paths, or automatic strong-ref dereferencing. A small set of explicit collection filter extensions may perform product-specific cross-record lookups; uploaded lexicons do not get these fields automatically.

For Hypercerts activities, use contributorDid when the caller needs to match inline contributor DIDs, legacy bare DID array entries, or org.hypercerts.claim.contributorInformation strong refs by referenced identifier:

where: { contributorDid: { eq: "did:plc:..." } }

For Certified badge awards, use badgeType to filter by the referenced app.certified.badge.definition.badgeType without joining badge definitions client-side:

where: { badgeType: { eq: "endorsement" } }

badgeType uses StringFilterInput, so it supports the same string operators exposed for badge definitions. Awards whose referenced badge definition is missing or has no badgeType do not match positive value filters.

For DID-rooted Certified endorsement networks, use endorsementClosure(where: ..., first: ..., after: ...):

query EndorsementClosure($did: String!) {
  endorsementClosure(
    where: { did: { eq: $did } }
    first: 100
  ) {
    truncated
    totalCount
    pageInfo { hasNextPage endCursor }
    edges {
      cursor
      node {
        did
        degree
        certifiedProfileData { did displayName avatar }
        viaAccounts {
          did
          certifiedProfileData { did displayName avatar }
        }
      }
    }
  }
}

where.did.eq is required and selects the root DID. The endorsement closure DID filter exposes only eq, not in, because each request is rooted at one DID. Optional where.degree.eq returns only one hop distance; the value must be 1, 2, or 3. Omit where.degree to return all supported degrees. Results are sorted by degree then DID. certifiedProfileData resolves the reached account's Certified profile when one exists. viaAccounts lists up to 64 previous-ring accounts that led to the account, including each predecessor DID and optional Certified profile data; it is empty for direct degree-1 accounts. truncated: true means the server-side account cap was reached. The resolver computes active endorsement edges from current Certified badge award, definition, and response records whose validationStatus is valid; invalid records cannot create or suppress edges. It only counts badge awards whose subject is the app.certified.defs#did account DID union member, ignores record strongRef subjects, respects badge-definition allowedIssuers allowlists, and does not use a persisted edge table.

If a workflow needs unsupported nested matching, use one of these patterns:

• Use typed nested/presence filters to narrow the set, then filter client-side.
• Use search(query: ..., collection: ...) to find records whose JSON contains a referenced AT-URI or string.
• Use records(collection: ...) as a fallback for collections without typed schema coverage or for raw debugging.

Validation gate and generic records

Hyperindex stores every observed AT Protocol record in its raw record table. Typed GraphQL collection fields only expose rows whose validationStatus is valid, meaning Indigo validated the record against the startup Lexicon set used to generate the running schema. Records whose status is invalid, unknown_schema, or validation_error are hidden from typed list queries, typed ByUri queries, typed counts, relationship hydration, and typed create/update subscriptions. Typed delete subscriptions emit only for rows that were valid before deletion.

Use generic records(collection: ...) or search(...) for operational visibility into raw rows, including records hidden from typed GraphQL. Generic record nodes expose validation metadata:

query RawRecords($collection: String!) {
  records(collection: $collection, first: 20) {
    edges {
      node {
        uri
        cid
        did
        collection
        rkey
        validationStatus
        validationError
        validatedAt
        lexiconHash
        value
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Validation is local-only during ingestion. Hyperindex uses Indigo to check records against the Lexicons loaded at startup and does not resolve _lexicon DNS records, DID documents, PDS-hosted schema records, or other remote schema sources while classifying records. lexiconHash is a validation fingerprint for the saved collection Lexicon and any transitive referenced Lexicons used during classification.

Public typed GraphQL, record validation, and default Jetstream collection filters use one fixed Lexicon set loaded at startup. Lexicon upload/register/delete changes only saved configuration; restart or redeploy Hyperindex to apply the change everywhere together. For multiple backend replicas, coordinate Lexicon-changing rollouts so old and new startup snapshots never serve concurrently against the shared validation metadata.

Generic recordEvents receives every observed raw create/update/delete event, including invalid and unknown-schema records. Typed collection subscriptions filter that stream to valid create/update rows and deletes that were valid before removal.

Generic record timeline

Use recordTimeline for cross-collection feeds ordered by the record JSON's top-level createdAt timestamp, not by indexer arrival time. Callers must pass where.collection.in; omit where.did for all authors, pass where.did.in to filter author DIDs, and pass where.did.in: [] only when an empty result is intended. first defaults to 50 and is capped at 1000. The connection intentionally has no totalCount.

query RecentCertifiedRecords($where: RecordTimelineWhereInput!, $after: String) {
  recordTimeline(
    where: $where
    first: 20
    after: $after
  ) {
    edges {
      cursor
      node {
        uri
        cid
        author { did handle }
        collection
        rkey
        createdAt
        indexedAt
        value
        certifiedProfileData { did displayName createdAt }
      }
    }
    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
  }
}

Variables:

{
  "where": {
    "collection": {
      "in": [
        "app.certified.actor.profile",
        "org.hypercerts.claim.activity",
        "org.hypercerts.collection"
      ]
    }
  },
  "after": null
}

Use typed collection queries when the caller needs collection-specific filters, sorting, exact totals, or typed fields. Use recordTimeline when the primary requirement is one stable newest-first page across selected collections.

External labeler filtering

Use external label filtering only after confirming that the target endpoint exposes external label support.

Supported schemas expose:

• Root query: externalLabels(subjects: ..., sources: ..., values: ..., activeOnly: ...)
• Record field: externalLabels(sources: ..., values: ..., activeOnly: ...)
• Record-label predicates: where.externalLabels.has and where.externalLabels.none
• Author-account label predicates: where.authorLabels.has and where.authorLabels.none

Use this pattern to get high-quality activity claims from source DID did:plc:antf7bsm6f4ohkqfdckefyt7:

query HighQualityActivityClaimsByLabeler($labeler: String!, $after: String) {
  orgHypercertsClaimActivity(
    first: 20
    after: $after
    sortBy: createdAt
    sortDirection: DESC
    where: {
      externalLabels: {
        has: {
          src: { eq: $labeler }
          val: { eq: "high-quality" }
          activeOnly: true
        }
      }
    }
  ) {
    edges {
      cursor
      node {
        uri
        cid
        did
        title
        shortDescription
        createdAt
        externalLabels(
          sources ]
           
           
         
          src
          uri
          cid
          val
          neg
          cts
          exp
          ver
        
      
    
    pageInfo  hasNextPage endCursor 
    totalCount
  

Variables:

{ "labeler": "did:plc:antf7bsm6f4ohkqfdckefyt7", "after": null }

externalLabels matches labels attached to the record AT-URI. To filter by labels attached to the record author's DID, use authorLabels instead. This is the right shape for orglabeler account labels such as likely-test, standard, and high-quality from did:plc:pswneepkd5lesumj7ejmkbal:

where: {
  authorLabels: {
    none: {
      src: { eq: "did:plc:pswneepkd5lesumj7ejmkbal" }
      val: { eq: "likely-test" }
      activeOnly: true
    }
  }
}

To require standard or high-quality authors:

where: {
  authorLabels: {
    has: {
      src: { eq: "did:plc:pswneepkd5lesumj7ejmkbal" }
      val: { in: ["standard", "high-quality"] }
      activeOnly: true
    }
  }
}

authorLabels only matches DID-subject labels with no CID. It does not infer labels from app.certified.actor.profile/self or organization records. There is no node-level authorLabels field; use the root externalLabels(subjects: [...]) query when you need to display labels for known author DIDs.

To combine record label filtering with author account label filtering, include both predicates:

where: {
  externalLabels: {
    has: {
      src: { eq: "did:plc:activity-labeler" }
      val: { eq: "verified-impact" }
      activeOnly: true
    }
  }
  authorLabels: {
    none: {
      src: { eq: "did:plc:pswneepkd5lesumj7ejmkbal" }
      val: { eq: "likely-test" }
      activeOnly: true
    }
  }
}

Use none to exclude labels:

where: {
  externalLabels: {
    none: { val: { eq: "low-quality" }, activeOnly: true }
  }
}

Use the root externalLabels query when you already have subject DIDs or AT-URIs and only need their labels:

query LabelsForSubjects($subjects: [String!]!, $labeler: String!) {
  externalLabels(
    subjects: $subjects
    sources: [$labeler]
    values: ["high-quality"]
    activeOnly: true
  ) {
    src
    uri
    cid
    val
    neg
    cts
    exp
    ver
  }
}

If an endpoint does not expose externalLabels, tell the consumer the selected hosted schema cannot filter by labels. Do not silently replace label filtering with text search; that can return false positives.

Consumer workflows

Get hypercerts for a specific DID

Use orgHypercertsClaimActivity and filter by author DID.

query HypercertsForDid($did: String!, $after: String) {
  orgHypercertsClaimActivity(
    first: 20
    after: $after
    sortBy: createdAt
    sortDirection: DESC
    where: { did: { eq: $did } }
  ) {
    edges {
      cursor
      node {
        uri
        cid
        author { did handle }
        rkey
        title
        shortDescription
        createdAt
        startDate
        endDate
        rights { uri cid }
        image {
          __typename
          ... on OrgHypercertsDefsUri { uri }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

Variables:

{ "did": "did:plc:...", "after": null }

Get a single hypercert by AT-URI

Use the ByUri query for a known AT-URI.

query HypercertByUri($uri: String!) {
  orgHypercertsClaimActivityByUri(uri: $uri) {
    uri
    cid
    author { did handle }
    rkey
    title
    shortDescription
    createdAt
    startDate
    endDate
    description {
      __typename
      ... on OrgHypercertsDefsDescriptionString { value }
      ... on ComAtprotoRepoStrongRef { uri cid }
    }
    contributors {
      contributionWeight
      contributorIdentity {
        __typename
        ... on OrgHypercertsClaimActivityContributorIdentity { identity }
        ... on ComAtprotoRepoStrongRef { uri cid }
      }
      contributionDetails {
        __typename
        ... on OrgHypercertsClaimActivityContributorRole { role }
        ... on ComAtprotoRepoStrongRef { uri cid }
      }
    }
    workScope { __typename }
    rights  uri cid 
  

Variables:

{ "uri": "at://did:plc:.../org.hypercerts.claim.activity/..." }

Get attachments relevant to a hypercert

org.hypercerts.context.attachment records connect to subjects through a subjects array of strong refs. When the endpoint exposes nested filters, find attachments for a specific hypercert AT-URI with subjects.any.uri.eq:

query AttachmentsForHypercert($hypercertUri: String!, $after: String) {
  orgHypercertsContextAttachment(
    first: 20
    after: $after
    sortBy: createdAt
    sortDirection: DESC
    where: { subjects: { any: { uri: { eq: $hypercertUri } } } }
  ) {
    edges {
      cursor
      node {
        uri
        title
        contentType
        createdAt
        subjects { uri cid }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{ "hypercertUri": "at://did:plc:.../org.hypercerts.claim.activity/...", "after": null }

If the endpoint does not expose subjects.any.uri, fall back to search(query: $hypercertUri, collection: "org.hypercerts.context.attachment") and filter the returned JSON client-side. If the caller only needs attachments that have any subject reference, use the typed presence check:

query AttachmentsWithSubjects($after: String) {
  orgHypercertsContextAttachment(
    first: 20
    after: $after
    sortBy: createdAt
    sortDirection: DESC
    where: { subjects: { isNull: false } }
  ) {
    edges {
      cursor
      node {
        uri
        title
        contentType
        createdAt
        subjects { uri cid }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{ "after": null }

Filter hypercerts with images

Use isNull on the field's generated filter input for complex top-level fields such as image. The input type may be a generated nested filter input rather than PresenceFilterInput.

query ActivityClaimsWithImages($after: String) {
  orgHypercertsClaimActivity(
    first: 20
    after: $after
    where: { image: { isNull: false } }
  ) {
    edges {
      cursor
      node {
        uri
        title
        image { __typename }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{ "after": null }

Sort hypercerts by activity dates or creation time

Use sortBy on orgHypercertsClaimActivity. Production sort fields are indexed_at, title, startDate, endDate, createdAt, and shortDescription.

query RecentActivity($after: String) {
  orgHypercertsClaimActivity(
    first: 20
    after: $after
    sortBy: startDate
    sortDirection: DESC
  ) {
    edges {
      cursor
      node { uri title did startDate endDate createdAt }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{ "after": null }

Use createdAt for client-declared record creation time. Use indexed_at when the consumer wants indexer arrival order.

Get a certified profile for a DID

Use appCertifiedActorProfile with the DID filter.

query CertifiedProfile($did: String!) {
  appCertifiedActorProfile(first: 1, where: { did: { eq: $did } }) {
    edges {
      cursor
      node {
        uri
        cid
        author { did handle }
        displayName
        description
        website
        pronouns
        createdAt
        avatar {
          __typename
          ... on OrgHypercertsDefsUri { uri }
        }
      }
    }
    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
  }
}

Variables:

{ "did": "did:plc:..." }

Get collections for a DID

query CollectionsForDid($did: String!, $after: String) {
  orgHypercertsCollection(
    first: 20
    after: $after
    sortBy: createdAt
    sortDirection: DESC
    where: { did: { eq: $did } }
  ) {
    edges {
      cursor
      node {
        uri
        title
        type
        shortDescription
        createdAt
        items {
          itemIdentifier { uri cid }
          itemWeight
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{ "did": "did:plc:...", "after": null }

Get EVM account links

Use appCertifiedLinkEvm for app.certified.link.evm records. Filter by author DID or EVM address when the consumer needs wallet-account links.

query EvmLinksForDid($did: String!, $after: String) {
  appCertifiedLinkEvm(
    first: 20
    after: $after
    where: { did: { eq: $did } }
    sortBy: createdAt
    sortDirection: DESC
  ) {
    edges {
      cursor
      node {
        uri
        cid
        did
        rkey
        address
        createdAt
        proof { __typename }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

Variables:

{ "did": "did:plc:...", "after": null }

Get record counts by collection

Use this for dashboards, health checks, and deciding which typed query to use.

query HypercertCollectionStats {
  collectionStats(collections: [
    "org.hypercerts.claim.activity",
    "org.hypercerts.context.attachment",
    "org.hypercerts.collection",
    "app.certified.actor.profile",
    "app.certified.link.evm"
  ]) {
    collection
    count
  }
}

Answering rules for agents

• Say “hypercert” when referring to org.hypercerts.claim.activity records unless the user is asking about another collection explicitly.
• Say “attachment” for org.hypercerts.context.attachment records.
• Say “certified profile” for app.certified.actor.profile records.
• Say “EVM link” or “wallet link” for app.certified.link.evm records.
• When giving user-facing parameterized examples, include both the query and variables.
• Prefer author { did handle } in record output selection sets. Keep using where.did for author filtering; only the direct output field is deprecated.
• When the schema has changed, prefer live introspection over this file and mention the endpoint used.