sanity（sanity 文档）

Sanity CMS Skill

Sanity API base: https://<projectId>.api.sanity.io/v2021-10-21

Env Vars

SANITY_PROJECT_ID=abc123
SANITY_DATASET=production   # or staging
SANITY_API_TOKEN=sk...      # from sanity.io/manage > API > Tokens
SANITY_BASE="https://$SANITY_PROJECT_ID.api.sanity.io/v2021-10-21"

GROQ Queries (Read)

Fetch All Documents of a Type

curl -G "$SANITY_BASE/data/query/$SANITY_DATASET" \
  -H "Authorization: Bearer $SANITY_API_TOKEN" \
  --data-urlencode 'query=*[_type == "post"]{_id, title, slug, publishedAt}'

Fetch Single Document by Slug

curl -G "$SANITY_BASE/data/query/$SANITY_DATASET" \
  -H "Authorization: Bearer $SANITY_API_TOKEN" \
  --data-urlencode 'query=*[_type == "post" && slug.current == $slug][0]' \
  --data-urlencode '$slug="my-blog-post"'

Complex Query with References

# Posts with author name resolved
*[_type == "post"]{title, "author": author->name, "category": category->title, body}

Count Documents

count(*[_type == "post"])

Mutations (Create/Update/Delete)

Create Document

curl -X POST "$SANITY_BASE/data/mutate/$SANITY_DATASET" \
  -H "Authorization: Bearer $SANITY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mutations": [{
      "create": {
        "_type": "post",
        "_id": "drafts.new-post-id",
        "title": "New Blog Post",
        "slug": {"_type": "slug", "current": "new-blog-post"},
        "publishedAt": "2026-03-27T00:00:00Z"
      }
    }]
  }'

Update Document (Patch)

curl -X POST "$SANITY_BASE/data/mutate/$SANITY_DATASET" \
  -H "Authorization: Bearer $SANITY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mutations": [{
      "patch": {
        "id": "<document_id>",
        "set": {"title": "Updated Title", "status": "published"}
      }
    }]
  }'

Delete Document

-d '{"mutations": [{"delete": {"id": "<document_id>"}}]}'

Publish Draft

# Move draft to published: delete draft, create published version
-d '{
  "mutations": [
    {"delete": {"id": "drafts.<doc_id>"}},
    {"createOrReplace": {"_id": "<doc_id>", "_type": "post", ...fields}}
  ]
}'

GROQ Syntax Reference

• Filter: *[_type == "post" && status == "published"]
• Sort: | order(publishedAt desc)
• Slice: [0...10]
• Projection: {title, "authorName": author->name}
• References: -> dereferences a reference field
• $param for query parameters (pass as $paramName=value)

Tips

• IDs starting with drafts. are unpublished drafts
• Use _rev field to detect conflicts on concurrent edits
• Token needs "Editor" role minimum for mutations; "Viewer" for queries only
• GROQ playground: sanity.io/manage > your project > Vision tab