Roblox Cloud

roblox-cloud

When to Use

Use this skill when the task is mainly about Roblox Open Cloud or HTTP-based integration work outside normal gameplay scripting:

• Building CI, bots, web backends, scripts, or internal tools that call Roblox web APIs.
• Choosing API keys for non-user automation and checking the required scopes for an endpoint.
• Constructing request URLs, bodies, filters, headers, pagination, update masks, or long-running operation polling.
• Handling Open Cloud errors, quota limits, retries, and rate-limit headers.
• Deciding whether an endpoint is usable from HttpService inside an experience.
• Receiving Roblox webhooks on Discord, Slack, or a custom HTTPS endpoint.
• Reading openapi.json, cloud.docs.json, or service-specific JSON files to generate clients or inspect endpoint metadata.

Do not use this skill when the task is mainly about:

• OAuth app registration, authorization flows, token exchange, refresh handling, or delegated user consent.
• DataStore or MemoryStore schema design, save architecture, or cross-server data strategy.
• Gameplay remotes, replication, or general Roblox engine scripting.

Decision Rules

• Use this skill if the core question is how to call or integrate with Roblox from HTTP.
• Prefer API keys when the caller is a server, CI job, bot, webhook worker, or in-experience automation that does not need end-user consent.
• Hand off to roblox-oauth when the integration needs user-granted access, OAuth registration, refresh tokens, or per-user delegated authorization.
• Hand off to roblox-data when the question becomes about persistent schema, contention, caching, or store-system design instead of request mechanics.
• Hand off to roblox-networking for gameplay networking, remotes, or trust-boundary questions.
• Hand off to roblox-api if the task is only an engine API lookup rather than a cloud integration.
• Use the machine-readable artifacts when you need exact path templates, schemas, scopes, rate limits, or HttpService usability metadata.
• If a request mixes cloud integration with out-of-scope architecture, answer only the Open Cloud portion and explicitly exclude the rest.

Instructions

1. Classify the caller and integration surface:

• External backend, CLI, CI, or automation worker.
• Webhook receiver.
• In-experience HttpService.

2. Choose authentication at the boundary:

• Default to API keys for non-user automation.
• If the task needs user-specific delegated access, stop and switch to roblox-oauth.

3. Confirm the endpoint before coding:

• Base URL and path template.
• Path and query parameters.
• Required request body schema.
• Required scopes.
• Rate limits.
• Whether HttpService is supported if the call originates in-experience.

4. Build requests using the documented patterns:

• Insert path parameters exactly.
• Keep pagination queries stable across pages.
• Add Content-Type: application/json for JSON bodies.
• Send x-api-key for API-key-authenticated requests.
• Use updateMask only for fields you intend to patch.

5. Handle Open Cloud response mechanics explicitly:

• Read nextPageToken for pagination.
• Poll Operation resources with backoff for long-running calls.
• Parse Open Cloud JSON types correctly, especially timestamps, durations, bytes, field masks, and decimals.

6. Handle failure paths as part of the integration:

• INVALID_ARGUMENT: verify IDs, filters, headers, and body shape.
• PERMISSION_DENIED or INSUFFICIENT_SCOPE: verify scopes and resource access.
• RESOURCE_EXHAUSTED or HTTP 429: honor retry-after when present, otherwise use exponential backoff.
• UNAVAILABLE and similar transient failures: retry with backoff, not tight loops.

7. For webhooks, design for secure, idempotent receipt:

• Require a public HTTPS POST endpoint.
• Return 2XX within 5 seconds.
• Verify roblox-signature when a secret is configured.
• Deduplicate by NotificationId.
• Treat deliveries as retryable and potentially duplicated.

8. For HttpService, apply the extra platform constraints:

• Only supported Open Cloud endpoints are callable.
• Only x-api-key and content-type headers are allowed.
• x-api-key must come from a Secret.
• HTTPS only.
• Path parameters cannot contain ..

9. Keep the answer inside scope:

• Focus on cloud requests, auth choice, webhooks, HttpService, rate limits, and tooling artifacts.
• Do not drift into OAuth implementation details, gameplay networking, or in-experience data architecture.

Using References

• Open references/open-cloud-overview.md first when you need the high-level model for Open Cloud versus legacy or in-experience calls.
• Open references/cloud-guides.md when the task matches a known workflow and you need the best guide starting point.
• Open references/api-patterns-errors-types-scopes-and-rate-limits.md for request construction, pagination, field masks, errors, scopes, and retry behavior.
• Open references/webhooks-documentation.md for trigger support, payload shape, signature verification, and delivery expectations.
• Open references/http-service.md when requests originate from a Roblox experience and endpoint support must be validated.
• Open references/openapi-documentation.md when you need to inspect or generate against the unified OpenAPI description.
• Open references/cloud-reference-json-files.md when you need to mine local JSON artifacts directly for operation IDs, schemas, scopes, or engine-usability metadata.

Checklist

• The integration surface is identified as external automation, webhook receiver, or in-experience HttpService.
• API key usage is chosen only for non-OAuth automation, and OAuth work is handed off when required.
• Endpoint path, body schema, scopes, and rate limits are confirmed before implementation.
• Pagination, filtering, and updateMask behavior are understood for the chosen endpoint.
• Long-running operations are polled instead of assumed synchronous.
• Error handling covers invalid input, permission failures, and quota exhaustion.
• Retry logic uses retry-after or exponential backoff.
• Webhooks are treated as idempotent, signed, and time-bounded.
• HttpService calls are checked for endpoint support and header limitations.
• The response stays out of OAuth implementation, data architecture, gameplay networking, and general engine scripting.

Common Mistakes

• Implementing OAuth flows here instead of switching to roblox-oauth.
• Assuming every Open Cloud endpoint is callable from HttpService.
• Sending unsupported headers from HttpService or storing the API key as plain text instead of a Secret.
• Forgetting that API-key scopes and creator permissions both matter.
• Changing filter parameters while paginating and then hitting 400 errors.
• Ignoring Operation polling and assuming async endpoints finish immediately.
• Retrying 429s or 503s in a tight loop instead of backing off.
• Treating webhook delivery as exactly once and skipping deduplication.
• Letting webhook handlers do slow work before returning a 2XX response.
• Expanding a cloud-integration question into save-schema, gameplay, or remote-security design.

Examples

External automation with an API key

• Use an API key for a CI job that publishes a place, updates a universe, or lists inventory items.
• Confirm the endpoint scope, build the request URL, and inspect rate-limit headers for safe batching.

In-experience Open Cloud call

• Before writing HttpService:RequestAsync, confirm the endpoint is supported for engine use.
• Put the API key in Secrets, send only x-api-key and content-type, and handle 429s with backoff.

Webhook receiver

• Configure a public HTTPS endpoint.
• Verify roblox-signature, reject stale timestamps, deduplicate by NotificationId, return 2XX quickly, and process the event asynchronously.

API Patterns, Errors, Types, Scopes, And Rate Limits

Key Concepts

• Open Cloud requests combine a base URL, path template, and optional query parameters.
• Many list endpoints paginate with maxPageSize, pageToken, and nextPageToken.
• Some endpoints return Operation resources that must be polled until done is true.
• Patch-style updates may use updateMask to limit which fields change.
• Open Cloud payloads use JSON plus special formats such as RFC 3339 timestamps, duration strings, base64 bytes, field masks, and decimal objects.
• Scopes define what the caller can do; rate limits define how often the caller can do it.

Rules

• Insert all path parameters exactly and do not mutate the rest of the query while paginating.
• Send Content-Type and a valid JSON body for endpoints that create or update resources.
• Confirm the endpoint's required scopes before implementation.
• Read x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset when available.
• Handle HTTP 429 with retry-after if present; otherwise use exponential backoff.
• Treat INVALID_ARGUMENT as a request-shape problem first and PERMISSION_DENIED or INSUFFICIENT_SCOPE as an auth or scope problem first.

Patterns

Pagination loop

GET ...?maxPageSize=100
-> read nextPageToken
GET ...?maxPageSize=100&pageToken=<token>

• Keep every other query parameter identical between pages.
• Stop when nextPageToken is empty or absent.

Long-running operation polling

POST or PATCH ... -> Operation
GET <operation path>
GET <operation path> after backoff

• Poll using the returned operation path.
• Back off between polls instead of hammering the endpoint.

Partial update with field masks

PATCH ...?updateMask=foo.bar,baz

• Include only the fields you intend to change.
• Align the JSON body with the mask.

Error triage

• 400 INVALID_ARGUMENT: bad ID, bad filter, bad header, or malformed body.
• 403 PERMISSION_DENIED or INSUFFICIENT_SCOPE: missing scope or no access to the target resource.
• 404 NOT_FOUND: wrong resource path or resource does not exist.
• 409 ABORTED: conflict state.
• 429 RESOURCE_EXHAUSTED: quota or rate limit exceeded.
• 5xx: transient or server-side failure; retry with backoff if safe.

Examples

Stable pagination

• Good: keep filter and maxPageSize unchanged while advancing pageToken.
• Bad: change filter between pages and reuse an old token.

Duration and timestamp handling

startTime: 2023-07-05T12:34:56Z
duration: 3s

Rate-limit-aware retry

• Read retry-after on 429.
• If it is absent, retry after 1s, 2s, 4s, and so on with a cap.

Cloud Guides

Key Concepts

• The cloud guides are workflow-oriented walkthroughs for common Open Cloud tasks.
• Guides usually include end-to-end request examples, required IDs, and resource-specific setup steps.
• They are useful when the question is about a concrete operational flow rather than a single endpoint lookup.
• Common guide areas include assets, inventory, configs, place publishing, universe messaging, notifications, instance APIs, and secrets usage.

Rules

• Start with a guide when the task describes a real workflow, not just one endpoint.
• Extract only the request mechanics, required identifiers, and sequence of calls that matter to the current integration.
• Use guides to discover the right API surface, then verify exact scopes, limits, and schemas in the reference or JSON artifacts.
• Do not let a guide pull the answer into out-of-scope data-architecture or OAuth-implementation detail.

Patterns

Use guides as workflow maps

• usage-place-publishing.md: publish places or place versions from automation.
• usage-messaging.md: send universe messages from the web.
• usage-assets.md: asset-related cloud workflows.
• inventory.md: user inventory retrieval flows.
• configs.md: config repository draft and publish workflows.
• instance.md: poll long-running instance operations.
• experience-notifications.md: notification sending workflows.

Extract the minimum implementation facts

From a guide, pull:

• Required resource IDs.
• Endpoint sequence.
• Request body shape.
• Polling or pagination behavior.
• Any scope or permission note that affects the caller.

Examples

Publishing automation

• Use the place publishing guide to confirm the correct universe ID, place ID, upload endpoint, and response handling.

Message broadcast tool

• Use the messaging guide to confirm the universe message endpoint, payload, and expected response behavior before coding the script.

In-experience secret-backed call

• Use the secrets-related guide material together with the HttpService docs when an API key must live inside Roblox-managed secrets.

Cloud Reference JSON Files

Key Concepts

• The local cloud reference artifacts live under sources/creator-docs/reference/cloud/.
• README.md explains that the reference site is rendered from these JSON files.
• openapi.json is the full cross-product OpenAPI document.
• cloud.docs.json is a doc-oriented cloud spec with Roblox extensions and resource metadata used by the documentation system.
• Service-specific files such as universes-api/v1.json, assets/v1.json, and developer-products-api/v1.json narrow the surface to one domain.

Rules

• Start with openapi.json when you need a global search across all Open Cloud endpoints.
• Use cloud.docs.json when doc metadata such as categories or resource naming is useful.
• Use service-specific v1.json files when you want the smallest artifact for a targeted tool or script.
• Read extension metadata such as scopes, engine usability, and rate limits from the JSON rather than guessing.
• If two artifacts disagree, verify against the published reference because these files are generated and evolving.

Patterns

Search by operation ID

rg -n operationId sources/creator-docs/reference/cloud

• Use this to locate the authoritative path, request body, and response shape.

Search for engine-usable endpoints

rg -n apiKeyWithHttpService sources/creator-docs/reference/cloud

• Use this when planning an in-experience integration.

Search for scope or rate-limit metadata

rg -n x-roblox-scopes sources/creator-docs/reference/cloud
rg -n x-roblox-rate-limits sources/creator-docs/reference/cloud

• Use this to confirm required permissions and quota envelopes before implementation.

Examples

Narrow artifact selection

• Use universes-api/v1.json when the task is only universe or place publishing automation.

Full-surface inspection

• Use openapi.json when building a generalized tool, Postman collection, or generated client.

Doc-metadata inspection

• Use cloud.docs.json when you need category labels, resource names, or richer documentation-oriented annotations.

HttpService

Key Concepts

• HttpService can call third-party web services and a subset of Open Cloud endpoints from inside Roblox experiences.
• HTTP requests must be enabled in Experience Settings before requests can be sent.
• Open Cloud requests from HttpService still require an API key.
• For Open Cloud calls, the API key must be provided from Roblox Secrets via HttpService:GetSecret(...).
• RequestAsync is the practical method when you need custom method, headers, or JSON body handling.

Rules

• Verify that the target endpoint is supported for engine use before writing the request.
• Only x-api-key and content-type headers are allowed for Open Cloud calls through HttpService.
• The x-api-key header value must be a Secret.
• Use HTTPS only.
• Do not include .. in Roblox-domain URL path parameters.
• Handle send failures with pcall and response failures through Success, StatusCode, StatusMessage, and Body.

Patterns

Supported request shape

local HttpService = game:GetService('HttpService')

local response = HttpService:RequestAsync({
    Url = 'https://apis.roblox.com/cloud/v2/groups/123',
    Method = 'GET',
    Headers = {
        ['x-api-key'] = HttpService:GetSecret('APIKey'),
    },
})

JSON body request

local response = HttpService:RequestAsync({
    Url = 'https://apis.roblox.com/cloud/v2/groups/123/memberships/456',
    Method = 'PATCH',
    Headers = {
        ['Content-Type'] = 'application/json',
        ['x-api-key'] = HttpService:GetSecret('APIKey'),
    },
    Body = HttpService:JSONEncode({
        role = 'groups/123/roles/789',
    }),
})

Rate-limit model

• Each server has a limit of 2500 Open Cloud requests per minute.
• Endpoint-specific limits per API key owner still apply on top of that.
• Open Cloud requests do not consume the separate general 500 HTTP requests per minute limit for other HTTP traffic.

Examples

Supported in-experience use

• Update a group membership or read a supported universe, place, group, or storage endpoint from a server script.

Failure handling

• Wrap the send in pcall, then branch on response.Success and response.StatusCode for retry or fallback logic.

Scope check before code

• Before using HttpService, inspect the reference JSON or docs for the endpoint's x-roblox-engine-usability and required scopes.

Open Cloud Overview

Key Concepts

• Roblox Open Cloud exposes Roblox resources through HTTP APIs under https://apis.roblox.com.
• Open Cloud is intended for external automation such as CLIs, CI jobs, web apps, bots, and operational tooling.
• Open Cloud also supports webhooks and a subset of endpoints through in-experience HttpService.
• Roblox recommends Open Cloud endpoints that support API keys or OAuth 2.0 over legacy cookie-authenticated APIs.
• For this skill, API keys are the default authentication choice for non-user automation.

Rules

• Prefer stable Open Cloud endpoints over legacy cookie-authenticated endpoints.
• Choose API keys for server-to-server, team-owned, or experience-owned automation that does not require user consent.
• If the integration needs user-delegated access or OAuth tokens, stop and switch to roblox-oauth.
• Keep the discussion on HTTP integration and request mechanics, not gameplay or engine architecture.

Patterns

Triage a cloud integration

1. Identify the caller: backend, CLI, CI, webhook receiver, or HttpService. 2. Find the endpoint and confirm the base URL and path template. 3. Confirm scopes, rate limits, and whether the endpoint works with HttpService. 4. Choose API key auth for non-user automation. 5. Implement retries, pagination, or polling if the endpoint requires them.

Basic request shape

GET https://apis.roblox.com/cloud/v2/...path...
x-api-key: <api key>

• Add Content-Type: application/json when the request includes a JSON body.
• Use exact IDs in path parameters rather than guessing resource names.

Examples

External automation

• A deployment script publishes places or updates universe settings through Open Cloud.

Operational bot

• A webhook worker receives a Roblox event and then calls an Open Cloud endpoint to continue an automation flow.

In-experience request

• A server script uses HttpService to call a supported Open Cloud endpoint with an API key stored in Secrets.

OpenAPI Documentation

Key Concepts

• Roblox publishes a unified OpenAPI document at sources/creator-docs/reference/cloud/openapi.json.
• The document follows OpenAPI 3.0.4 and covers the Roblox Cloud API surface.
• The spec is useful for Swagger, Postman, code generation, validation tooling, and direct schema inspection.
• Roblox adds vendor extensions that capture metadata not expressed by base OpenAPI alone.

Rules

• Use the spec for exact path templates, parameter shapes, request bodies, and schemas.
• Inspect vendor extensions before generating or calling clients blindly.
• Treat the document as a generated artifact under active development and verify suspicious details against published docs or narrower JSON files.
• Do not turn spec usage into OAuth flow implementation inside this skill.

Patterns

High-value vendor extensions

• x-roblox-stability: release state such as beta.
• x-roblox-deprecated: extra deprecation guidance.
• x-roblox-alternatives: replacement guidance where present.
• x-roblox-rate-limits: per-authentication quota metadata.
• x-roblox-scopes: required scopes.
• x-roblox-engine-usability: whether the endpoint is usable from HttpService.

What to inspect per operation

1. operationId 2. parameters 3. requestBody 4. responses 5. security 6. x-roblox-scopes 7. x-roblox-rate-limits 8. x-roblox-engine-usability

Minimal extension example

operationId: Cloud_UpdateUniverse
x-roblox-scopes: universe:write
x-roblox-engine-usability: apiKeyWithHttpService = true

Examples

Generate a client safely

• Use openapi.json as the source, then manually review generated auth handling, polling models, and field-mask support before shipping.

Check engine support

• Read x-roblox-engine-usability.apiKeyWithHttpService before assuming an endpoint can be called from a Roblox server.

Check rate limits

• Read x-roblox-rate-limits to estimate batching and retry pressure before load-testing the integration.

Webhooks Documentation

Key Concepts

• Roblox webhooks push event data to a third-party URL or custom HTTPS endpoint when a supported event occurs.
• Current supported trigger families include subscription events, compliance right-to-erasure events, and commerce order events.
• Webhooks can target Discord, Slack, or a custom endpoint, but Roblox only fully supports Discord and Slack integrations.
• Each payload includes fixed fields: NotificationId, EventType, EventTime, and an EventPayload object.
• Delivery is retry-based, and duplicates are possible.

Rules

• The webhook URL must be publicly reachable over HTTPS, accept POST, and return a 2XX response within 5 seconds.
• Verify roblox-signature when a secret is configured.
• Deduplicate events by NotificationId.
• Treat webhook handling as idempotent because retries and duplicates can occur.
• Return success quickly and move slower processing to a queue or worker.
• Enforce a replay window by checking the signature timestamp against current time.

Patterns

Receiver flow

1. Receive POST payload. 2. Parse roblox-signature. 3. Rebuild <timestamp>.<raw body>. 4. Compute HMAC-SHA256 with the shared secret and compare signatures. 5. Reject stale timestamps. 6. Check whether NotificationId was already processed. 7. Enqueue or process the event. 8. Return 2XX quickly.

Signature format

t=<timestamp>,v1=<signature>

• If no secret is configured, only the timestamp is present.

Payload contract

NotificationId: string
EventType: RightToErasureRequest
EventTime: 2023-12-30T16:24:24.2118874Z
EventPayload:
  UserId: 1
  GameIds: 1234, 2345

Examples

Duplicate-safe handling

• If the same NotificationId arrives twice, process it once and acknowledge the duplicate without re-running side effects.

Fast acknowledgment

• Return a 2XX immediately after signature verification and dedupe checks, then do slower work off the request path.

Test flow

• Use the Creator Dashboard test action and validate receipt of SampleNotification before turning on production triggers.