Hygraph Integration

RankAscend publishes content to Hygraph via the Content API (GraphQL). For each article, it creates an entry in your configured model, maps title, slug, body, and meta description to your fields, then immediately publishes it from draft to live, all in a single automated flow.

Connecting Hygraph

Go to Settings → Integrations → Hygraph and provide two values:

Name
Content API URL
Type
string
Description
Your Hygraph project's GraphQL endpoint. Find it in Project Settings → API Access → Content API (e.g. https://api-region.hygraph.com/v2/{projectId}/master).
Name
Permanent Auth Token
Type
string
Description
A long-lived token with write permissions on the Content API. Generate one in Project Settings → API Access → Permanent Auth Tokens. Make sure the token has at least the Editor role on your content stage.

When you save, RankAscend sends a lightweight introspection query ({ __typename }) to verify the token. Credentials are encrypted at rest.

Per-content-type configuration

Hygraph models vary per project, so you map each RankAscend content type to a Hygraph model under Settings → Integrations → Hygraph → Content Types:

Name
Model API ID
Type
string
Description
Required. The API ID of the Hygraph model to publish into (e.g. BlogPost, Article, Page). Find this in Hygraph's Schema view, it's the name shown in the model header. Leave blank to skip a content type entirely.

Expand Advanced field mapping to override the default field names if your model uses different names:

Name
Title field
Type
string
Description
Default: title. The Hygraph field that receives the article title.
Name
Slug field
Type
string
Description
Default: slug. The Hygraph field that receives the URL slug.
Name
Body field
Type
string
Description
Default: content. The Hygraph field that receives the article body.
Name
Body field type
Type
"string" | "richtext"
Description
Default: string. Set to richtext if your body field uses Hygraph's Rich Text type, RankAscend will pass { markdown: "..." } and Hygraph will convert it to its internal AST. Set to string to pass raw Markdown text.
Name
Meta description field
Type
string
Description
Default: metaDescription. The Hygraph field that receives the SEO meta description.

How publishing works

Publishing runs as a two-stage GraphQL workflow:

Stage 1, Create draft

RankAscend builds and executes a create mutation against your model. For a model named BlogPost with default field mapping and a richtext body, the mutation looks like:

RankAscend dynamically generates the mutation based on your model ID and field mapping. You never write this GraphQL, it's built from your configuration.

If bodyFieldType is "string", the $body variable type changes to String! and receives the raw Markdown text.

Stage 1: create mutation

mutation CreateEntry(
  $title: String!
  $slug: String!
  $body: RichTextAST!
  $meta: String!
) {
  createBlogPost(data: {
    title: $title
    slug: $slug
    content: $body
    metaDescription: $meta
  }) {
    id
  }
}

Stage 2, Publish

RankAscend immediately publishes the draft entry to the PUBLISHED stage using the entry ID returned from Stage 1:

Both mutations run in the same publish job. If Stage 1 fails, Stage 2 never runs. If Stage 2 fails, the entry exists in Hygraph as a draft, you can publish it manually from the Hygraph content editor.

Stage 2: publish mutation

mutation PublishEntry($id: ID!) {
  publishBlogPost(
    where: { id: $id }
    to: [PUBLISHED]
  ) {
    id
  }
}

Error handling

Error	Cause	Fix
`Hygraph integration is not configured`	No API URL or token saved	Complete the Hygraph setup in Settings
`No Hygraph model configured for content type "{type}"`	Model API ID is blank for this content type	Add the model ID in Settings → Integrations → Hygraph
`Hygraph create failed: ...`	GraphQL errors returned from the create mutation	Check field names match your model schema; verify token permissions
`Hygraph create succeeded but returned no entry ID`	Unexpected response from Hygraph API	Check your Hygraph project status and API limits
`Hygraph publish failed: ...`	GraphQL errors returned from the publish mutation	The draft was created, publish it manually in Hygraph if needed

If Stage 2 (publish) fails, the content exists in Hygraph as a draft. RankAscend marks the job as failed and will retry it, but the retry will attempt to create a new entry, not publish the existing draft. Delete the draft in Hygraph before the retry runs to avoid duplicate entries.

Failed jobs are retried automatically every 30 minutes. You can also reschedule any failed job manually from the Publish Log.

Disconnecting Hygraph

Go to Settings → Integrations → Hygraph → Remove. RankAscend deletes the stored credentials. Revoke the token in Hygraph under Project Settings → API Access → Permanent Auth Tokens if you want to fully remove access.