Home/Treatment Management/Insert Surface

Insert Surface

This document provides a guide and overview for the InsertSurface RPC, which allows you to register a Surface directly via API. A Surface must exist before it can be referenced by name in InsertTreatmentType or UpdateTreatmentType, so this endpoint removes the manual console step from an otherwise API-driven treatment type integration.

API Definition

POST https://apis.auxia.io/v1/InsertSurface

note

InsertSurface requires a Treatment Management API key, passed in the x-api-key header. A key without Treatment Management permissions is rejected with 403 PERMISSION_DENIED. The key is validated against the projectId in the request: a key issued for one project cannot create a Surface on another.

Entities

SurfacePb

message SurfacePb {
  // The Surface name. Surfaces are referenced by name everywhere in the API,
  // so there is no separate Auxia-side identifier to store.
  string surface_name = 1;
}

InsertSurface

API to register a Surface

message InsertSurfaceRequest {
  // Required.
  // Numeric project id.
  string project_id = 1;

  // Required.
  // Must match ^[A-Za-z][A-Za-z0-9_]*$, with a maximum length of 200 characters.
  // Cannot be "All" in any casing.
  string surface_name = 2;

  // Required.
  // Identifies who made the change, for audit purposes. Typically an email address.
  string last_modified_by = 3;
}

message InsertSurfaceResponse {
  // The registered Surface (or the pre-existing one, if it already existed).
  SurfacePb surface = 1;
}

Surface name rules

Rule	Detail
Pattern	^[A-Za-z][A-Za-z0-9_]*$
First character	Must be a letter. A leading digit is rejected.
Allowed	Upper case, lower case, digits (not first), underscore
Rejected	Hyphens, spaces, and any other punctuation
Max length	200 characters
Reserved	All, in any casing

tip

InsertSurface is idempotent on (project_id, surface_name). Calling it again with the same project and name returns the existing Surface without creating a duplicate or returning an error. Retrying after a network timeout is therefore always safe, and there is no need to track which Surfaces have already been created - call it unconditionally before referencing a Surface by name.

caution

Surfaces cannot be deleted. Creating one also provisions the per-Surface event schemas and data fields behind it. Validate the name on your side before calling, since a typo results in a permanent Surface.

Sample cURL Request

curl --location --request POST 'https://apis.auxia.io/v1/InsertSurface' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data-raw '{
  "projectId": "PROJECT_ID",
  "surfaceName": "IN_APP_CONTENT",
  "lastModifiedBy": "USER_EMAIL"
}'

Sample Response

{
  "surface": {
    "surfaceName": "IN_APP_CONTENT"
  }
}

Errors

HTTP	Condition
400	surfaceName does not match the required pattern, for example a leading digit or a hyphen
400	surfaceName is the reserved value All, in any casing
400	surfaceName or lastModifiedBy is empty, or projectId is not numeric
403	The API key does not have Treatment Management permissions
403	The API key is valid but belongs to a different project
403	No API key was supplied

Registering a Surface and a Treatment Type together

InsertTreatmentType and UpdateTreatmentType validate that every Surface named in surfaces already exists for the project, and reject the request with 400 otherwise:

{"code":400,"message":"The following surfaces do not exist for project_id PROJECT_ID: IN_APP_CONTENT"}

Call InsertSurface first for each Surface name, then reference those names in the treatment type request:

1. POST /v1/InsertSurface for each Surface the treatment type will use
2. POST /v1/InsertTreatmentType with surfaces: [{ "surfaceName": "IN_APP_CONTENT" }]
3. POST /v1/InsertTreatment to add content to the treatment type

Because step 1 is idempotent, it is safe to run on every treatment type creation rather than only the first time a Surface is used.