GraphQL API

Homecast exposes two GraphQL endpoints:

Endpoint	Auth	Purpose
GET/POST /	JWT	Web and mobile app (first-party)
GET/POST /graphql	OAuth / Token	Programmatic access

Both serve the same schema. Use /graphql with access tokens or OAuth for integrations.

curl -X POST https://api.homecast.cloud/graphql \
  -H "Authorization: Bearer hc_your_token" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ homes { id name } }"}'

Field name convention

All field names are camelCase in GraphQL (e.g., homeMembers, accessTokens). Python source uses snake_case which is auto-converted.

Auth & Account

Queries

Field	Returns	Description
me	UserInfo	Current user profile
account	AccountInfo	Account type, subscription status
settings	UserSettings	User settings JSON
health	String	Server health check

Mutations

Field	Parameters	Returns	Description
signup	email, password, name?	AuthResult	Create account
login	email, password	AuthResult	Sign in
verifyEmail	token	AuthResult	Verify email address
resendVerificationEmail	email	AuthResult	Resend verification
updateSettings	data (JSON string)	UpdateSettingsResult	Update user settings
createCheckoutSession	region?	CheckoutSessionResult	Start Stripe checkout
createPortalSession	—	PortalSessionResult	Open billing portal

Types

type AuthResult {
  success: Boolean!
  token: String
  user: UserInfo
  error: String
}

type UserInfo {
  id: String!
  email: String!
  name: String
  accountType: String!
  emailVerified: Boolean!
}

Homes & Rooms

Queries

Field	Parameters	Returns	Description
homes	—	[HomeKitHome]	All accessible homes
cachedHomes	—	[CachedHome]	Cached homes with relay status
rooms	homeId	[HomeKitRoom]	Rooms in a home
zones	homeId	[HomeKitZone]	Zones in a home
serviceGroups	homeId	[HomeKitServiceGroup]	Service groups
scenes	homeId	[HomeKitScene]	Scenes in a home

Types

type HomeKitHome {
  id: String!
  name: String!
  role: String       # owner, admin, control, view
}

type CachedHome {
  homeId: String!
  name: String!
  role: String
  isConnected: Boolean
  memberCount: Int
}

type HomeKitRoom {
  id: String!
  name: String!
  homeId: String!
}

type HomeKitScene {
  id: String!
  name: String!
  homeId: String!
}

Accessories & Control

Queries

Field	Parameters	Returns	Description
accessories	homeId?, roomId?	[HomeKitAccessory]	List accessories
accessory	accessoryId, homeId?	HomeKitAccessory	Get single accessory
characteristicGet	accessoryId, characteristicType, homeId?	CharacteristicValue	Read a characteristic

Mutations

Field	Parameters	Returns	Description
setCharacteristic	accessoryId, characteristicType, value, homeId?	SetCharacteristicResult	Set a device characteristic
setServiceGroup	homeId, groupId, characteristicType, value	SetServiceGroupResult	Control all devices in a group
executeScene	sceneId, homeId?	ExecuteSceneResult	Execute a HomeKit scene

Types

type HomeKitAccessory {
  id: String!
  name: String!
  homeId: String!
  roomId: String!
  category: String
  reachable: Boolean!
  services: [HomeKitService!]!
}

type HomeKitService {
  id: String!
  type: String!
  name: String
  characteristics: [HomeKitCharacteristic!]!
}

type HomeKitCharacteristic {
  type: String!
  value: JSON
  description: String
  format: String
  unit: String
  minValue: Float
  maxValue: Float
  minStep: Float
  validValues: [String]
  canRead: Boolean!
  canWrite: Boolean!
}

type SetCharacteristicResult {
  success: Boolean!
  value: JSON
  error: String
}

Collections & Layout

Queries

Field	Parameters	Returns	Description
storedEntities	entityType	[StoredEntityInfo]	List stored entities
storedEntityLayout	entityType, entityId	StoredEntityInfo	Get entity layout

Mutations

Field	Parameters	Returns	Description
syncEntities	entities (JSON array)	SyncEntitiesResult	Sync entity data
updateStoredEntityLayout	entityType, entityId, layoutJson	UpdateEntityLayoutResult	Update layout

Home Members

Queries

Field	Parameters	Returns	Description
homeMembers	homeId	[HomeMemberInfo]	Members of a home
mySharedHomes	—	[CachedHome]	Homes shared with me
pendingInvitations	—	[PendingInvitation]	My pending invitations

Mutations

Field	Parameters	Returns	Description
inviteHomeMember	homeId, email, role	HomeMemberResult	Invite by email
updateHomeMemberRole	homeId, email, role	HomeMemberResult	Change member role
removeHomeMember	homeId, email	HomeMemberResult	Remove a member
acceptPendingInvitation	invitationId	HomeMemberResult	Accept an invitation
rejectPendingInvitation	invitationId	HomeMemberResult	Reject an invitation

Types

type HomeMemberInfo {
  id: String!
  homeId: String!
  email: String!
  role: String!          # admin, control, view
  isPending: Boolean!
  createdAt: String!
  name: String
}

type PendingInvitation {
  id: String!
  homeId: String!
  homeName: String
  role: String!
  inviterName: String
  createdAt: String!
}

Entity Sharing

Queries

Field	Parameters	Returns	Description
sharingInfo	entityType, entityId	SharingInfo	Sharing summary for an entity
entityAccess	entityType, entityId	[EntityAccessInfo]	Access entries for an entity
mySharedEntities	—	[EntityAccessInfo]	Entities I've shared
publicEntity	shareHash, passcode?	SharedEntityData	Get shared entity (no auth)
publicEntityAccessories	shareHash, passcode?	[HomeKitAccessory]	Accessory data for shared entity

Mutations

Field	Parameters	Returns	Description
createEntityAccess	entityType, entityId, accessType, role?, homeId?, userEmail?, passcode?, name?, accessSchedule?	CreateEntityAccessResult	Share an entity
updateEntityAccess	accessId, role?, passcode?, name?, accessSchedule?	CreateEntityAccessResult	Update sharing
deleteEntityAccess	accessId	DeleteEntityAccessResult	Remove sharing
publicEntitySetCharacteristic	shareHash, passcode?, accessoryId, characteristicType, value	PublicEntitySetResult	Control via share link

Access Tokens

Queries

Field	Parameters	Returns	Description
accessTokens	—	[AccessTokenInfo]	List all tokens

Mutations

Field	Parameters	Returns	Description
createAccessToken	name, homePermissions, expiresAt?	CreateAccessTokenResult	Create a token
revokeAccessToken	tokenId	RevokeAccessTokenResult	Revoke a token

Webhooks

Queries

Field	Parameters	Returns	Description
webhooks	—	[WebhookInfo]	List all webhooks
webhook	webhookId	WebhookInfo	Get single webhook
webhookEventTypes	—	[WebhookEventTypeInfo]	Available event types
webhookDeliveryHistory	webhookId, offset?, limit?	DeliveryHistoryResult	Delivery history

Mutations

Field	Parameters	Returns	Description
createWebhook	name, url, eventTypes?, homeIds?, roomIds?, accessoryIds?, collectionIds?, maxRetries?, rateLimitPerMinute?, timeoutMs?	CreateWebhookResult	Create a webhook
updateWebhook	webhookId, name?, url?, eventTypes?, homeIds?, roomIds?, accessoryIds?, collectionIds?, maxRetries?, rateLimitPerMinute?, timeoutMs?	UpdateWebhookResult	Update a webhook
deleteWebhook	webhookId	DeleteWebhookResult	Delete a webhook
pauseWebhook	webhookId	UpdateWebhookResult	Pause deliveries
resumeWebhook	webhookId	UpdateWebhookResult	Resume deliveries
rotateWebhookSecret	webhookId	RotateSecretResult	Rotate signing secret
testWebhook	webhookId	TestWebhookResult	Send test delivery

Types

type WebhookInfo {
  id: String!
  name: String!
  url: String!
  secretPrefix: String!
  status: String!           # active, paused, disabled
  eventTypes: [String!]!
  homeIds: [String!]!
  roomIds: [String!]!
  accessoryIds: [String!]!
  collectionIds: [String!]!
  maxRetries: Int!
  rateLimitPerMinute: Int
  timeoutMs: Int!
  consecutiveFailures: Int!
  lastTriggeredAt: String
  lastSuccessAt: String
  lastFailureAt: String
  createdAt: String
}

OAuth Apps

Queries

Field	Parameters	Returns	Description
authorizedApps	—	[AuthorizedAppInfo]	OAuth apps with access

Mutations

Field	Parameters	Returns	Description
revokeAuthorizedApp	clientId	RevokeAuthorizedAppResult	Revoke app access

Sessions

Queries

Field	Parameters	Returns	Description
sessions	—	[SessionInfo]	Active sessions
session	deviceId	SessionInfo	Get single session
connectionDebugInfo	—	ConnectionDebugInfo	Debug info

Mutations

Field	Parameters	Returns	Description
removeSession	deviceId	Boolean	Remove a session

Backgrounds

Queries

Field	Parameters	Returns	Description
backgroundPresets	—	[BackgroundPresetInfo]	Available preset backgrounds
userBackgrounds	—	[UserBackgroundInfo]	User's uploaded backgrounds

Examples

Read all accessories in a home

{
  homes {
    id
    name
    rooms {
      id
      name
      accessories {
        id
        name
        category
        reachable
        services {
          type
          characteristics {
            type
            value
          }
        }
      }
    }
  }
}

Set a device characteristic

mutation {
  setCharacteristic(
    accessoryId: "acc-uuid"
    characteristicType: "brightness"
    value: "50"
    homeId: "home-uuid"
  ) {
    success
    value
    error
  }
}

Create an access token

mutation {
  createAccessToken(
    name: "My Script"
    homePermissions: "{\"home-uuid\": \"control\"}"
  ) {
    success
    rawToken
    error
  }
}

Create a webhook

mutation {
  createWebhook(
    name: "State logger"
    url: "https://my-server.com/webhook"
    eventTypes: ["state.changed"]
    homeIds: ["home-uuid"]
  ) {
    success
    webhook {
      id
      name
      secretPrefix
    }
    error
  }
}

List shared homes

{
  mySharedHomes {
    homeId
    name
    role
  }
}

See API Errors for error response formats and common issues.