Custom Endpoint Service

The Custom Endpoint Service allows you to create and manage custom API endpoints within the Conscia DX Engine. Use this service to configure custom endpoint routes, manage endpoint configurations, and set up custom domains with CNAME records to route requests from your domain to Conscia.

How Custom Endpoints Work

Custom endpoints act as a bridge between your external API requests and the DX Engine. When you create a custom endpoint:

1. Define the Request: Specify the HTTP method, path, and host for incoming requests
2. Map to DX Engine: Configure which DX Engine template to execute and what context to pass
3. Configure the Response: Define how the DX Engine response should be returned to the caller

The endpoint intercepts requests at the specified path and host, passes the request parameters to the DX Engine template as context, executes the template, and returns the response.

Example Flow

1. Client makes a request to https://api.yourdomain.com/products/search/shoes?categoryId=123
2. The api.yourdomain.com host points to endpoint.conscia.io via CNAME.
3. Custom endpoint extracts categoryId from params
4. Endpoint calls DX Engine template with context: { "contextA": "123" }
5. DX Engine executes template and returns orchestrated response
6. Endpoint returns the response to the client

Managing Custom Endpoints

The Custom Endpoint Service provides a complete set of CRUD (Create, Read, Update, Delete) operations for managing your custom endpoints through the DX Engine API.

Available Operations

• Create a new custom endpoint
• List all custom endpoints
• Get details of a specific endpoint
• Update an existing endpoint configuration
• Delete an endpoint

All endpoint management operations use the /endpoints path in the DX Engine API.

Authentication

All requests must include the following headers:

X-Customer-Code: {{customerCode}}
Authorization: Bearer {{dxEngineToken}}
Content-Type: application/json

---

Create Custom Endpoint

Create a new custom endpoint configuration.

HTTP Method: POST
Path: /endpoints

Request Body

{
  "endpoint": {
    "endpointRequestSpec": {
      "method": "POST",
      "path": "/products/search/shoes",
      "host": "api.yourdomain.com"
    },
    "engineRequest": {
      "environmentCode": "production",
      "apiKey": "your-api-key",
      "templateCode": "my-template",
      "context": {
        "contextA": "`params.categoryId`"
      }
    },
    "endpointResponse": {
      "body": "`engineResponse`",
      "headers": {
        "content-type": "application/json"
      }
    },
    "endpointCode": "search-product-category"
  }
}

Response

{
  "success": true
}

---

Get Custom Endpoint

Retrieve details of a specific custom endpoint.

HTTP Method: GET
Path: /endpoints/{endpointCode}

Example

GET /endpoints/search-product-category

Response

{
  "success": true,
  "endpoint": {
    "endpointCode": "search-product-category",
    "endpointRequestSpec": {
      "method": "POST",
      "path": "/products/search/shoes",
      "host": "api.yourdomain.com"
    },
    "engineRequest": {
      "environmentCode": "production",
      "apiKey": "your-api-key",
      "templateCode": "my-template",
      "context": {
        "contextA": "`params.categoryId`"
      }
    },
    "endpointResponse": {
      "body": "`engineResponse`",
      "headers": {
        "content-type": "application/json"
      }
    }
  }
}

---

List Custom Endpoints

Retrieve all custom endpoints for your account.

HTTP Method: GET
Path: /endpoints

Response

{
  "success": true,
  "endpoints": [
    {
      "endpointCode": "search-product-category",
      "endpointRequestSpec": {
        "method": "POST",
        "path": "/products/search/shoes",
        "host": "api.yourdomain.com"
      },
      "engineRequest": {
        "environmentCode": "production",
        "templateCode": "my-template"
      }
    },
    {
      "endpointCode": "get-product-details",
      "endpointRequestSpec": {
        "method": "GET",
        "path": "/products/:productId",
        "host": "api.yourdomain.com"
      },
      "engineRequest": {
        "environmentCode": "production",
        "templateCode": "product-detail-template"
      }
    }
  ]
}

---

Update Custom Endpoint

Update an existing custom endpoint configuration.

HTTP Method: PATCH
Path: /endpoints/{endpointCode}

Request Body

{
  "endpoint": {
    "endpointRequestSpec": {
      "method": "POST",
      "path": "/products/search/updated-path",
      "host": "api.yourdomain.com"
    },
    "engineRequest": {
      "environmentCode": "staging",
      "apiKey": "updated-api-key",
      "templateCode": "updated-template",
      "context": {
        "contextA": "`params.categoryId`",
        "contextB": "`params.brand`"
      }
    },
    "endpointResponse": {
      "body": "`engineResponse`",
      "headers": {
        "content-type": "application/json",
        "cache-control": "no-cache"
      }
    }
  }
}

Response

{
  "success": true,
  "endpoint": {
    "endpointCode": "search-product-category",
    "endpointRequestSpec": {
      "method": "POST",
      "path": "/products/search/updated-path",
      "host": "api.yourdomain.com"
    },
    "engineRequest": {
      "environmentCode": "staging",
      "apiKey": "updated-api-key",
      "templateCode": "updated-template",
      "context": {
        "contextA": "`params.categoryId`",
        "contextB": "`params.brand`"
      }
    },
    "endpointResponse": {
      "body": "`engineResponse`",
      "headers": {
        "content-type": "application/json",
        "cache-control": "no-cache"
      }
    }
  }
}

---

Delete Custom Endpoint

Delete a custom endpoint.

HTTP Method: DELETE
Path: /endpoints/{endpointCode}

Response

{
  "success": true
}

---

Request Body Parameters

Endpoint Object

The main endpoint object contains the following nested objects:

endpointRequestSpec

Defines the incoming request specification for your custom endpoint.

Parameter	Type	Required	Description
method	string	Yes	HTTP method (GET, POST, PUT, PATCH, DELETE)
path	string	Yes	URL path for the endpoint (e.g., /products/search/shoes)
host	string	Yes	Host domain for the endpoint (e.g., api.yourdomain.com)

engineRequest

Configures how the endpoint interacts with DX Engine.

Parameter	Type	Required	Description
environmentCode	string	No	DX Engine environment code (e.g., production, staging)
apiKey	string	No	API key for DX Engine authentication
templateCode	string	Yes	DX Engine template code to execute
context	object	No	Context parameters to pass to the template. Use backticks with params. to reference request parameters (e.g., `params.categoryId`)

endpointResponse

Defines the response structure from your custom endpoint.

Parameter	Type	Required	Description
body	string	Yes	Response body template. Use `engineResponse` to return the DX Engine response
headers	object	No	HTTP response headers (e.g., {"content-type": "application/json"})

endpointCode

Parameter	Type	Required	Description
endpointCode	string	Yes	Unique identifier for the endpoint (alphanumeric and hyphens only)

---

Setting Up CNAME for Custom Domain

To use your own custom domain for Conscia API requests, you'll need to configure a CNAME record with your DNS provider. This allows you to route requests from your domain (e.g., api.yourdomain.com) to Conscia's infrastructure.

Prerequisites

• Access to your domain's DNS management console
• A custom domain or subdomain you want to use
• Your Conscia account must be configured to accept requests from your custom domain

Step 1: Contact Conscia Support

Before configuring your DNS, contact Conscia support to:

1. Inform them of your custom domain (e.g., api.yourdomain.com)
2. Request that your domain be added to the allowlist
3. Receive confirmation that your account is configured for custom domain support

Contact: support@conscia.com

Step 2: Configure CNAME Record

Once your domain is approved, add a CNAME record in your DNS settings:

DNS Configuration

Record Type	Host/Name	Value/Target	TTL
CNAME	api	engine.conscia.io	3600

Note: The "Host/Name" field should be your subdomain (e.g., api for api.yourdomain.com)

Example DNS Configurations

For production endpoints:

Host: api
Type: CNAME
Value: engine.conscia.io
TTL: 3600 (or 1 hour)

For staging endpoints:

Host: api-staging
Type: CNAME
Value: engine-staging.conscia.io
TTL: 3600

Step 3: Verify CNAME Configuration

After adding the CNAME record, verify it's properly configured using one of these methods:

Using Command Line (macOS/Linux)

dig api.yourdomain.com CNAME

or

nslookup api.yourdomain.com

Using Online Tools

Use online DNS lookup tools like:

• https://dnschecker.org
• https://mxtoolbox.com/DNSLookup.aspx

Troubleshooting

DNS Not Resolving

• Wait for propagation: DNS changes can take up to 48 hours to propagate globally, though typically complete within 1 hour
• Clear DNS cache: Try flushing your local DNS cache or use a different network
• Check TTL: Ensure your previous DNS records have expired

SSL/TLS Certificate Errors

• Conscia automatically provisions SSL certificates for approved custom domains
• If you see certificate errors, wait 10-15 minutes after DNS propagation for certificate issuance
• Contact Conscia support if errors persist beyond 24 hours

404 or 403 Errors

• Verify your custom domain is allowlisted with Conscia support
• Check that you're using the correct API path

Security Considerations

1. HTTPS Only: All custom domain requests are automatically redirected to HTTPS
2. Certificate Management: Conscia handles SSL certificate provisioning and renewal
3. Rate Limiting: Standard Conscia rate limits apply to custom domain requests

Example Implementation

Once configured, you can make requests to your custom domain:

// Create a custom endpoint
const createEndpoint = await fetch('https://endpoint.conscia.io/api/endpoints', {
  method: 'POST',
  headers: {
    'X-Customer-Code': 'YOUR_CUSTOMER_CODE',
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    endpoint: {
      endpointRequestSpec: {
        method: 'POST',
        path: '/products/search/shoes',
        host: 'api.yourdomain.com'
      },
      engineRequest: {
        environmentCode: 'your-conscia-env',
        apiKey: 'your-api-key',
        templateCode: 'product-search-template',
        context: {
          category: '`params.categoryId`',
          brand: '`params.brand`'
        }
      },
      endpointResponse: {
        body: '`engineResponse`',
        headers: {
          'content-type': 'application/json'
        }
      },
      endpointCode: 'search-products'
    }
  })
});

const result = await createEndpoint.json();
console.log(result);

---

Using Your Custom Endpoint

Once created, your custom endpoint is immediately available at the specified host and path. Here's how to call it:

// Call your custom endpoint
const response = await fetch('https://api.yourdomain.com/products/search/shoes?categoryId=athletic', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filters: {
      size: [9, 10],
      color: ['black', 'white']
    }
  })
});

const products = await response.json();
console.log(products);

The custom endpoint will:

1. Extract categoryId from the query parameters
2. Pass it to the DX Engine template as context
3. Execute the template with your specified configuration
4. Return the orchestrated response

---

Related Documentation

• Experience API
• Connections
• Webhooks
• Flows
• DX Engine Servers