Customers

Customers represent organizations or entities that use your product. Each customer is identified by an external_id drawn from your telemetry system (the value used in WHERE clauses to isolate that customer’s requests). Firetiger hashes the external ID to produce a URL-safe resource name.

Service: firetiger.customers.v2.CustomersService

Resource name pattern: customers/{customer_id}

Access: Read-write

Resource type: Customer

Example flow

Create a customer, list customers to confirm it exists, then update a field.

1. Create a customer

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.customers.v2.CustomersService/CreateCustomer" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "acme-corp",
    "customer": {
      "external_id": "acme-corp",
      "display_name": "Acme Corporation",
      "description": "Enterprise SaaS customer on the Business plan",
      "runbook": "Check dashboard at https://internal.example.com/acme for SLO status before escalating."
    }
  }'

{
  "customer": {
    "name": "customers/acme-corp",
    "externalId": "acme-corp",
    "id": "65a3089e664b",
    "displayName": "Acme Corporation",
    "description": "Enterprise SaaS customer on the Business plan",
    "runbook": "Check dashboard at https://internal.example.com/acme for SLO status before escalating.",
    "createTime": "2024-08-10T12:00:00Z",
    "updateTime": "2024-08-10T12:00:00Z"
  }
}

2. List customers

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.customers.v2.CustomersService/ListCustomers" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "customers": [
    {
      "name": "customers/acme-corp",
      "externalId": "acme-corp",
      "id": "65a3089e664b",
      "displayName": "Acme Corporation",
      "description": "Enterprise SaaS customer on the Business plan",
      "createTime": "2024-08-10T12:00:00Z",
      "updateTime": "2024-08-10T12:00:00Z"
    }
  ],
  "nextPageToken": ""
}

3. Update the customer’s description

Use update_mask to change only specific fields. Fields not in the mask are left untouched.

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.customers.v2.CustomersService/UpdateCustomer" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "customers/acme-corp",
      "description": "Enterprise SaaS customer, upgraded to Premium plan"
    },
    "update_mask": "description"
  }'

{
  "customer": {
    "name": "customers/acme-corp",
    "externalId": "acme-corp",
    "id": "65a3089e664b",
    "displayName": "Acme Corporation",
    "description": "Enterprise SaaS customer, upgraded to Premium plan",
    "runbook": "Check dashboard at https://internal.example.com/acme for SLO status before escalating.",
    "createTime": "2024-08-10T12:00:00Z",
    "updateTime": "2024-08-10T12:05:00Z"
  }
}

Methods

Method Description
CreateCustomer Create a new customer
GetCustomer Retrieve a customer by name
UpdateCustomer Update an existing customer
DeleteCustomer Soft-delete a customer
ListCustomers List customers with filtering and pagination

CreateCustomer

Create a new customer.

POST /firetiger.customers.v2.CustomersService/CreateCustomer

Request body

Field Type Required Description
customer_id string Yes ID for the new customer (alphanumeric, hyphens, underscores; must start with a letter or digit)
customer Customer Yes The customer to create (must include external_id)

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.customers.v2.CustomersService/CreateCustomer" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "acme-corp",
    "customer": {
      "external_id": "acme-corp",
      "display_name": "Acme Corporation",
      "description": "Enterprise SaaS customer on the Business plan",
      "runbook": "Check dashboard at https://internal.example.com/acme for SLO status before escalating."
    }
  }'

Response

{
  "customer": {
    "name": "customers/acme-corp",
    "externalId": "acme-corp",
    "id": "65a3089e664b",
    "displayName": "Acme Corporation",
    "description": "Enterprise SaaS customer on the Business plan",
    "runbook": "Check dashboard at https://internal.example.com/acme for SLO status before escalating.",
    "createTime": "2024-08-10T12:00:00Z",
    "updateTime": "2024-08-10T12:00:00Z"
  }
}

GetCustomer

Retrieve a customer by name.

POST /firetiger.customers.v2.CustomersService/GetCustomer

Request body

Field Type Required Description
name string Yes Resource name of the customer

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.customers.v2.CustomersService/GetCustomer" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "customers/acme-corp"}'

UpdateCustomer

Update an existing customer. Use update_mask to specify which fields to modify.

POST /firetiger.customers.v2.CustomersService/UpdateCustomer

Request body

Field Type Required Description
customer Customer Yes The customer with name set and updated fields
update_mask string No Comma-separated list of fields to update. If omitted, all provided fields are updated.

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.customers.v2.CustomersService/UpdateCustomer" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "customers/acme-corp",
      "description": "Enterprise SaaS customer, upgraded to Premium plan"
    },
    "update_mask": "description"
  }'

DeleteCustomer

Soft-delete a customer. The resource will still be accessible via Get but excluded from List results unless show_deleted is set.

POST /firetiger.customers.v2.CustomersService/DeleteCustomer

Request body

Field Type Required Description
name string Yes Resource name of the customer to delete

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.customers.v2.CustomersService/DeleteCustomer" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "customers/acme-corp"}'

ListCustomers

List customers with optional filtering and pagination.

POST /firetiger.customers.v2.CustomersService/ListCustomers

Request body

Field Type Required Description
filter string No Filter expression
order_by string No Field to sort by (e.g. create_time desc)
page_size integer No Maximum results per page
page_token string No Token for the next page of results
show_deleted boolean No Include soft-deleted customers

Filter examples

  • display_name : '*acme*' – substring match on display name
  • external_id = 'acme-corp' – exact match on external ID
  • create_time > '2024-01-01T00:00:00Z' – customers created after a date

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.customers.v2.CustomersService/ListCustomers" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"filter": "display_name : \"*Acme*\"", "page_size": 25}'

Response

{
  "customers": [
    {
      "name": "customers/acme-corp",
      "externalId": "acme-corp",
      "id": "65a3089e664b",
      "displayName": "Acme Corporation",
      "description": "Enterprise SaaS customer on the Business plan",
      "createTime": "2024-08-10T12:00:00Z",
      "updateTime": "2024-08-10T12:00:00Z"
    }
  ],
  "nextPageToken": ""
}

A v1 API (firetiger.customers.v1.CustomersService) is also available but deprecated. Use v2 for new integrations.

This site uses Just the Docs, a documentation theme for Jekyll.