Site Settings

The Settings API manages site configurations that control which domains are allowed to send analytics events.

All endpoints require an OAuth 2.0 Bearer token with the appropriate scope.

List Settings

Retrieve all site configurations for your organization.

GET /v1/settings

Authentication: OAuth Bearer

Scope: insightcore:settings.read

Rate Limit: 100/min

Response

{
  "data": [
    {
      "setting_id": "stc_00000k1L2m3N4o5",
      "organization_id": "org_00000a1B2c3D4e5",
      "allowed_domains": ["mystore.com", "www.mystore.com"],
      "settings": {
        "session_timeout": 1800,
        "bot_filtering": true
      },
      "is_active": true,
      "created_at": "2026-03-26T12:00:00Z",
      "updated_at": "2026-03-26T12:00:00Z"
    }
  ]
}

Create Setting

Register a new site configuration.

POST /v1/settings

Authentication: OAuth Bearer

Scope: insightcore:settings.write

Rate Limit: 100/min

Request Body

{
  "allowed_domains": ["mystore.com", "www.mystore.com"],
  "settings": {
    "session_timeout": 1800,
    "bot_filtering": true
  }
}

Request Fields

Field	Type	Required	Description
allowed_domains	array	No	List of domains allowed to send events
allowed_domains[]	string	—	A domain name (e.g., mystore.com)
settings	object	No	Site-specific configuration options

Settings Object

Key	Type	Default	Description
session_timeout	integer	1800	Session timeout in seconds
bot_filtering	boolean	true	Filter known bot traffic from reports

Response

201 Created:

{
  "data": {
    "setting_id": "stc_00000k1L2m3N4o5",
    "organization_id": "org_00000a1B2c3D4e5",
    "allowed_domains": ["mystore.com", "www.mystore.com"],
    "settings": {
      "session_timeout": 1800,
      "bot_filtering": true
    },
    "is_active": true,
    "created_at": "2026-03-26T12:00:00Z",
    "updated_at": "2026-03-26T12:00:00Z"
  }
}

Get Setting

Retrieve a single site configuration by ID.

GET /v1/settings/{setting_id}

Authentication: OAuth Bearer

Scope: insightcore:settings.read

Path Parameters

Parameter	Type	Description
setting_id	string	Setting identifier (e.g., stc_00000k1L2m3N4o5)

Response

{
  "data": {
    "setting_id": "stc_00000k1L2m3N4o5",
    "organization_id": "org_00000a1B2c3D4e5",
    "allowed_domains": ["mystore.com", "www.mystore.com"],
    "settings": {
      "session_timeout": 1800,
      "bot_filtering": true
    },
    "is_active": true,
    "created_at": "2026-03-26T12:00:00Z",
    "updated_at": "2026-03-26T12:00:00Z"
  }
}

Update Setting

Update an existing site configuration.

PUT /v1/settings/{setting_id}

Authentication: OAuth Bearer

Scope: insightcore:settings.write

Path Parameters

Parameter	Type	Description
setting_id	string	Setting identifier

Request Body

All fields are optional. Only provided fields are updated.

{
  "allowed_domains": ["mystore.com", "www.mystore.com", "shop.mystore.com"],
  "settings": {
    "session_timeout": 3600,
    "bot_filtering": true
  },
  "is_active": true
}

Request Fields

Field	Type	Required	Description
allowed_domains	array	No	Replacement list of allowed domains
settings	object	No	Replacement settings object
is_active	boolean	No	Enable or disable the configuration

Response

200 OK:

{
  "data": {
    "setting_id": "stc_00000k1L2m3N4o5",
    "organization_id": "org_00000a1B2c3D4e5",
    "allowed_domains": ["mystore.com", "www.mystore.com", "shop.mystore.com"],
    "settings": {
      "session_timeout": 3600,
      "bot_filtering": true
    },
    "is_active": true,
    "created_at": "2026-03-26T12:00:00Z",
    "updated_at": "2026-03-26T14:30:00Z"
  }
}

Delete Setting

Soft-delete a site configuration. Events will no longer be accepted for domains in this configuration.

DELETE /v1/settings/{setting_id}

Authentication: OAuth Bearer

Scope: insightcore:settings.write

Path Parameters

Parameter	Type	Description
setting_id	string	Setting identifier

Response

204 No Content

---

Changelog

Date	Change
2026-03-26	Initial publication.