Cloud quickstart

PlainQ Cloud brings your organization’s teams, queues, and Pub/Sub topics together in a hosted workspace. PlainQ prepares the underlying infrastructure from your organization’s selected plan.

Cloud is currently in early access. Paid subscriptions are not enabled yet.

1. Create an organization

Open the Cloud dashboard using Get started on the PlainQ website, then sign in or create an account. Create your organization and choose its plan. A General team is created for you.

Wait for the workspace to finish preparing before creating resources. You do not need to select or configure a server.

2. Organize your teams

Use Teams to create a team for each group of applications or people. An organization administrator can assign current organization members to teams. Members can work with resources in their assigned teams.

Choose the organization and team in the sidebar before creating a queue or topic. Queue and topic limits are shared across the organization.

3. Create a queue and an API key

In Queues, create a queue named jobs. Copy its queue ID.

In API keys, create a key for the selected team. Copy the secret when it is shown; it is only displayed once. Keep it in your application’s environment.

Open Connection guide and copy the team’s endpoint. Set PLAINQ_URL to that endpoint followed by /api/v1, as shown in the guide:

export PLAINQ_URL='https://app.plainq.dev/q/YOUR_ORG_ID/YOUR_TEAM_ID/api/v1'
export PLAINQ_API_KEY='YOUR_TEAM_API_KEY'
export QUEUE_ID='YOUR_QUEUE_ID'

The hostname above is an example. Use the full endpoint from your own workspace’s Connection guide.

4. Send a message

Message bodies are base64-encoded UTF-8. This example sends “hello, plainq”:

curl -X POST "$PLAINQ_URL/queue/$QUEUE_ID/messages" \
  -H "Authorization: Bearer $PLAINQ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"body":"aGVsbG8sIHBsYWlucQ=="}]}'

5. Receive and acknowledge

Receive a message, process it, and use its returned message ID to acknowledge it:

curl -X POST "$PLAINQ_URL/queue/$QUEUE_ID/messages/receive?batch=1" \
  -H "Authorization: Bearer $PLAINQ_API_KEY"

export MESSAGE_ID='RECEIVED_MESSAGE_ID'
curl -X POST "$PLAINQ_URL/queue/$QUEUE_ID/messages/ack" \
  -H "Authorization: Bearer $PLAINQ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"messageIds\":[\"$MESSAGE_ID\"]}"

Acknowledging a message removes it from the queue. A visibility timeout lets another worker retry a message that was received but not acknowledged.

Add Pub/Sub

In Pub/Sub, create a topic and connect queues from the same team. Publish an event to the topic to deliver a copy to each connected queue. Each queue can be processed independently.

You can also use the HTTP API through the same team endpoint:

• Create a topic at /queue/topics.
• Connect a queue at /queue/topics/$TOPIC_ID/subscriptions.
• Publish messages at /queue/topics/$TOPIC_ID/publish.

Every request uses the same team API key. Keys cannot access another team’s queues or topics.