> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a topic

> Name a topic, choose its delivery defaults, and prepare it for subscriptions.

A topic is the publishing destination for a group of subscriptions. Create one
per stream of events that shares access rules and delivery defaults, such as
`order-events` or `production-alerts`. Filters let subscribers select a subset
of that stream without requiring another topic.

## Create the topic

Select the account and region where publishers and subscribers will operate.
Creating a topic requires `notifications:CreateTopic`; see
[permissions](/notifications/permissions).

<Tabs>
  <Tab title="Console">
    1. Open **Notifications** and select **Create Topic**.
    2. Enter a **Name**, such as `production-alerts`.
    3. Optionally enter a **Display name** and **Tags**.
    4. Select **Create topic**. The console opens the topic's page.

    Add recipients from its **Subscriptions** tab. A topic with no confirmed,
    matching subscriptions accepts publications but delivers nothing.
  </Tab>

  <Tab title="API">
    Send this request to `https://notifications.sa-saopaulo-1.basaltic.sh`,
    with the authentication headers described in [Authentication](/authentication).

    ```http theme={null}
    POST /v1/topics
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "name": "production-alerts",
      "display_name": "Production alerts",
      "tags": { "environment": "production" }
    }
    ```

    A successful response is HTTP `201`, with the resource in `topic`.
    Save `topic.id` for nested subscription, message, and delivery requests.
    Use `topic.crn` in IAM policies.
  </Tab>

  <Tab title="CLI">
    Save the JSON request from the API tab as `request-1.json`. Use your configured account and region.

    ```bash theme={null}
    basaltic notifications topic create --from-file request-1.json
    ```
  </Tab>

  <Tab title="Go">
    Save the JSON request from the API tab as `request-1.json`. Configure credentials, account, and region through the SDK environment variables.

    ```go theme={null}
    package main

    import (
    	"context"
    	"encoding/json"
    	"fmt"
    	"os"

    	basaltic "github.com/basaltic-sh/sdk-go"
    	"github.com/basaltic-sh/sdk-go/notifications"
    )

    func readJSON(path string, value any) error {
    	data, err := os.ReadFile(path)
    	if err != nil {
    		return err
    	}
    	return json.Unmarshal(data, value)
    }

    func run() error {
    	ctx := context.Background()
    	cfg, err := basaltic.NewConfig(ctx)
    	if err != nil {
    		return err
    	}
    	client := notifications.New(cfg)
    	var request1 notifications.CreateTopicRequest
    	if err := readJSON("request-1.json", &request1); err != nil {
    		return err
    	}
    	result1, err := client.CreateTopic(ctx, &request1)
    	if err != nil {
    		return err
    	}
    	fmt.Printf("%+v\n", result1)
    	return nil
    }

    func main() {
    	if err := run(); err != nil {
    		fmt.Fprintln(os.Stderr, err)
    		os.Exit(1)
    	}
    }
    ```
  </Tab>
</Tabs>

## Choose a stable name

Names contain 1–256 ASCII letters, digits, dots, dashes, or underscores and
start with a letter or digit. A name must be unique in the account and region.
UUID names and the `crn:` prefix are reserved. The name is immutable and forms
the topic CRN, so choose it before writing access policies.

The display name is optional and can be changed. It is limited to 100 bytes
and is used as the email subject when a publication has no subject.

## Delivery defaults

The console creation form uses the platform retry policy. The API accepts a
`delivery_policy` object at creation or in `PATCH /v1/topics/{topic_id}`:

```json theme={null}
{
  "delivery_policy": {
    "max_attempts": 6,
    "min_delay_seconds": 20,
    "max_delay_seconds": 1200,
    "timeout_seconds": 15
  }
}
```

Each subscription can override individual fields. An omitted subscription
field inherits the topic's value, then the platform default. See
[delivery and retries](/notifications/delivery#retry-policy) for the ranges
and which failures are retried.

## Next steps

[Create a subscription](/notifications/creating-subscriptions), then
[publish a message](/notifications/publishing). Open the topic's **Metrics**
tab to observe publishing and delivery rates. Deleting a topic also deletes
its subscriptions, published message records, and delivery records.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.