Skip to content

Creating Applications

Create a new application to define which traffic Shield should process.

Endpoint

POST /api/apps

Creates a new application with URL filters that determine which traffic to scan.

Authentication

Requires API Key with Policy Definition permission.

Request Body

Field Type Required Description
name string Yes Application name (1-64 chars)
description string No Description (0-128 chars)
urlFilters array Yes Array of URL filter objects (at least one required)

URL Filter Object

Field Type Required Description
filterType integer Yes Filter type: 0=Domain, 1=Hostname, 2=Path, 3=Regex - see Filter Types
isWhitelist boolean Yes true = scan only these URLs, false = scan except these URLs
filter string Yes Filter pattern (format depends on filterType)
contentType string[] No MIME types to match (e.g., ["application/json", "text/html"])
methods string[] No HTTP methods to match (e.g., ["GET", "POST"])
comment string No Description of this filter
runContentTypeDetection boolean No Auto-detect content type if header is missing (default: false)
htmlOptions object No HTML-specific options for advanced filtering

Response

Returns the created application object with an id field:

Response Format 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "External APIs",
  "description": "Third-party API integrations",
  "urlFilters": [
    {
      "filterType": 1,
      "isWhitelist": false,
      "contentType": ["application/json"],
      "methods": ["POST", "PUT"],
      "filter": "api.external.com",
      "comment": "Match all requests to api.external.com",
      "runContentTypeDetection": true
    }
  ],
  "createdAt": 1704067200,
  "updatedAt": 1704067200
}

Examples

Create Application for JSON APIs

Create an application to scan JSON traffic from payment APIs.

curl -X POST "https://your-shield-host:8080/api/apps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment APIs",
    "description": "All payment processing endpoints",
    "urlFilters": [
      {
        "filterType": 1,
        "isWhitelist": false,
        "contentType": ["application/json"],
        "methods": ["POST", "PUT"],
        "filter": "payment.api.company.com",
        "comment": "Payment API hostname",
        "runContentTypeDetection": true
      }
    ]
  }'

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

app = {
    "name": "Payment APIs",
    "description": "All payment processing endpoints",
    "urlFilters": [
        {
            "filterType": 1,  # Hostname
            "isWhitelist": False,  # Scan these URLs
            "contentType": ["application/json"],
            "methods": ["POST", "PUT"],
            "filter": "payment.api.company.com",
            "comment": "Payment API hostname",
            "runContentTypeDetection": True
        }
    ]
}

response = requests.post(f"{BASE_URL}/api/apps", headers=HEADERS, json=app)
app_id = response.json()["id"]
print(f"Created app: {app_id}")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const app = {
  name: 'Payment APIs',
  description: 'All payment processing endpoints',
  urlFilters: [
    {
      filterType: 1,  // Hostname
      isWhitelist: false,  // Scan these URLs
      contentType: ['application/json'],
      methods: ['POST', 'PUT'],
      filter: 'payment.api.company.com',
      comment: 'Payment API hostname',
      runContentTypeDetection: true
    }
  ]
};

const response = await axios.post(`${BASE_URL}/api/apps`, app, { headers: HEADERS });
const appId = response.data.id;
console.log(`Created app: ${appId}`);
Create Domain-Wide Application

Scan all traffic for an entire domain.

curl -X POST "https://your-shield-host:8080/api/apps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal Apps",
    "description": "All internal company applications",
    "urlFilters": [
      {
        "filterType": 0,
        "filter": "company.com",
        "isWhitelist": false,
        "comment": "Scan all company.com subdomains"
      }
    ]
  }'

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

app = {
    "name": "Internal Apps",
    "description": "All internal company applications",
    "urlFilters": [
        {
            "filterType": 0,  # Domain
            "filter": "company.com",
            "isWhitelist": False,
            "comment": "Scan all company.com subdomains"
        }
    ]
}

response = requests.post(f"{BASE_URL}/api/apps", headers=HEADERS, json=app)
print(f"Created app: {response.json()['id']}")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const app = {
  name: 'Internal Apps',
  description: 'All internal company applications',
  urlFilters: [
    {
      filterType: 0,  // Domain
      filter: 'company.com',
      isWhitelist: false,
      comment: 'Scan all company.com subdomains'
    }
  ]
};

const response = await axios.post(`${BASE_URL}/api/apps`, app, { headers: HEADERS });
console.log(`Created app: ${response.data.id}`);
Create Regex-Based Application

Use regex for complex URL matching patterns.

curl -X POST "https://your-shield-host:8080/api/apps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Versioned APIs",
    "description": "All versioned API endpoints (v1, v2, etc.)",
    "urlFilters": [
      {
        "filterType": 3,
        "filter": "^https://api\\.company\\.com/v[0-9]+/.*$",
        "isWhitelist": false,
        "contentType": ["application/json"],
        "comment": "Match /v1/, /v2/, /v3/, etc."
      }
    ]
  }'

import requests

BASE_URL = "https://your-shield-host:8080"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

app = {
    "name": "Versioned APIs",
    "description": "All versioned API endpoints (v1, v2, etc.)",
    "urlFilters": [
        {
            "filterType": 3,  # Regex
            "filter": "^https://api\\.company\\.com/v[0-9]+/.*$",
            "isWhitelist": False,
            "contentType": ["application/json"],
            "comment": "Match /v1/, /v2/, /v3/, etc."
        }
    ]
}

response = requests.post(f"{BASE_URL}/api/apps", headers=HEADERS, json=app)
print(f"Created app: {response.json()['id']}")

const axios = require('axios');

const BASE_URL = 'https://your-shield-host:8080';
const HEADERS = { 'Authorization': 'Bearer YOUR_API_KEY' };

const app = {
  name: 'Versioned APIs',
  description: 'All versioned API endpoints (v1, v2, etc.)',
  urlFilters: [
    {
      filterType: 3,  // Regex
      filter: '^https://api\\.company\\.com/v[0-9]+/.*$',
      isWhitelist: false,
      contentType: ['application/json'],
      comment: 'Match /v1/, /v2/, /v3/, etc.'
    }
  ]
};

const response = await axios.post(`${BASE_URL}/api/apps`, app, { headers: HEADERS });
console.log(`Created app: ${response.data.id}`);

Error Responses

Status Code Description Solution
400 Invalid request body Check field validation requirements
401 Invalid or expired API key Verify authentication
403 Insufficient permissions Key needs Policy Definition permission
409 Application name already exists Use a unique name or update the existing application