Insert Surface - Auxia Docs

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

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

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:

POST /v1/InsertSurface for each Surface the treatment type will use
POST /v1/InsertTreatmentType with surfaces: [{ "surfaceName": "IN_APP_CONTENT" }]
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.

​API Definition

​Entities

​SurfacePb

​InsertSurface

​API to register a Surface

​Surface name rules

​Sample cURL Request

​Sample Response

​Errors

​Registering a Surface and a Treatment Type together

API Definition

Entities

SurfacePb

InsertSurface

API to register a Surface

Surface name rules

Sample cURL Request

Sample Response

Errors

Registering a Surface and a Treatment Type together