Hive API And Integrations

Hive API And Integrations

Use this skill when the user needs Hive API requests, runnable scripts, webhook workflows, technical discovery, implementation guidance, or troubleshooting.

API Surfaces

• REST base URL: https://app.hive.com/api/v1
• GraphQL endpoint: https://prod-gql.hive.com/graphql
• Hive MCP endpoint: https://hive-mind.hive.com/mcp

Prefer Hive MCP for live workspace reads/writes inside Claude Code. Use REST or GraphQL when the user needs external requests, scripts, or integration examples.

Use REST for straightforward CRUD, webhook creation/deletion, and file-oriented endpoints. Use GraphQL for nested reads, rich filtering, cursor pagination, and query-heavy reporting.

Authentication

For Claude Code live operations, prefer OAuth through /mcp.

For raw REST or GraphQL requests:

• user_id goes in query params.
• api_key goes in request headers.
• Credentials come from Hive: Main Menu > My Profile > API Info.
• Never hardcode, log, or commit credentials.

Credential smoke test:

curl -sS \
  -H "api_key: $HIVE_API_KEY" \
  "https://app.hive.com/api/v1/testcredentials?user_id=$HIVE_USER_ID"

Integration Workflow

1. Identify source system, trigger, object mapping, success criteria, scale, and owner.
2. Resolve workspace, project, user, label, status, and custom field IDs before writing code.
3. Produce the smallest runnable artifact: curl, GraphQL operation with variables, TypeScript script, Python script, or webhook receiver.
4. Validate auth, IDs, field names, enum casing, pagination, and date/timezone behavior.

Ground Rules

• Use exact field names from docs, MCP schemas, live GraphQL introspection, or existing examples. Do not guess.
• Set Content-Type: application/json for JSON POST/PUT requests.
• Convert estimates to seconds before sending them.
• Use exact status casing.
• Check HTTP status codes and response bodies.
• Retry transient 429 and 5xx failures with backoff when appropriate.
• Keep dependent writes sequential unless API semantics clearly allow batching.

Webhooks

When designing webhook integrations:

1. Build and verify the receiver before creating the Hive webhook.
2. Add shared-secret validation through explicit headers or another verification mechanism.
3. Validate trigger, webhook ID, and record identifiers on receipt.
4. Make processing idempotent.
5. Return success quickly and process asynchronously.
6. Scope webhooks tightly with project IDs and fields when possible.

Useful triggers include actions::i, actions::u, projects::i, and projects::u.

Response Shape

Lead with the artifact, then include short assumptions, auth notes, required placeholders, and validation steps. Prefer requests and scripts over broad advice.