Create and test functions

Early access. This feature is in early access, which means it’s undergoing ongoing testing and development while we gather feedback, validate functionality, and improve outputs. Contact the C1 Support team if you’d like to try it out or share feedback.

This guide walks you through creating your first function, from a simple “hello world” to accessing C1 data and calling external APIs.

Use the copilot to write function code

Not sure where to start with TypeScript or the C1 API? The built-in AI code assistant can generate a working function from a plain-language description of what you want it to do — no TypeScript expertise required. Since functions start as drafts, you can try out the generated code, run it, and iterate safely before publishing. To get started, click Create with AI when creating a new function, or click Edit with AI in the code editor of an existing function draft. Describe what you want your function to do, and the AI assistant will generate code to get you started. You can then edit the code as needed, run it with test inputs, and publish when you’re ready.

Step 1: Set up a new function

Navigate to Workflows > Functions.

Click New function.

Enter a name and optional description, then click Create.

You’re taken to the detail page with a built-in code editor (Monaco, TypeScript mode). The editor includes two files: main.ts for your function code and main.test.ts for tests.

Step 2: Write function code

Every function must export a main function that accepts input and returns a result. Both input and output are JSON objects.

Visit the functions reference for detailed documentation on SDK namespaces, configuration options, and troubleshooting advice.

Basic structure

import { JSONObject } from "@c1/functions-sdk";

export default async function main(input: JSONObject): Promise<JSONObject> {
    return {
        message: "Hello from my first function!",
        timestamp: new Date().toISOString()
    };
}

Use input parameters

Accept input to make your function interactive:

import { JSONObject } from "@c1/functions-sdk";

export default async function main(input: JSONObject): Promise<JSONObject> {
    const name = input.name as string || "World";

    return {
        greeting: `Hello, ${name}!`,
        timestamp: new Date().toISOString()
    };
}

Test with input:

{"name": "Alice"}

Output:

{
  "greeting": "Hello, Alice!",
  "timestamp": "2026-02-09T12:07:45.272Z"
}

Access C1 data

Use the pre-authenticated sdk object to query data from your C1 tenant.

Functions authenticate to the C1 API as a service principal. Before publishing, link a service principal whose roles match what your function needs to do. See Step 5: Link a service principal for API access below.

List users

import { JSONObject, sdk } from "@c1/functions-sdk";

export default async function main(input: JSONObject): Promise<JSONObject> {
    const users = await sdk.user.list();

    return {
        userCount: users.userServiceListResponse?.list?.length ?? 0,
    };
}

Get a specific user

import { JSONObject, sdk } from "@c1/functions-sdk";

export default async function main(input: JSONObject): Promise<JSONObject> {
  const userId = input.userId as string;

  const userResponse = await sdk.user.get({ id: userId });

  return {
    success: true,
    user: userResponse.user,
  };
}

Search users

import { JSONObject, sdk } from "@c1/functions-sdk";

export default async function main(input: JSONObject): Promise<JSONObject> {
  const searchResponse = await sdk.userSearch.search({
    query: "Engineering",
  });

  return {
    success: true,
    results: searchResponse.list,
  };
}

For a complete list of SDK operations, see SDK namespaces.

Use secrets and configuration

Store API keys and configuration values securely in your function’s config.

Set secrets in the UI

Navigate to your function and click Edit config (in the more menu).

In the Secrets section, add key/value pairs.

Click Save.

Access secrets in code

import { JSONObject, functions } from "@c1/functions-sdk";

export default async function main(input: JSONObject): Promise<JSONObject> {
    const config = await functions.getConfig();
    console.log('got config', config);

    return {
      secretNumber: config.secrets.SECRET_NUMBER
    };
}

Call external APIs

External domains must be added to Outbound Network Access in your function’s config before you can call them. See Outbound network access.

import { JSONObject, functions } from "@c1/functions-sdk";
import { Octokit } from "npm:@octokit/rest@1.2.3";

export default async function main(input: JSONObject): Promise<JSONObject> {
    // 1. Get secrets from config
    const config = await functions.getConfig();
    const token = config.secrets["GITHUB_TOKEN"];

    if (!token) {
        throw new Error("GitHub Token not found in config");
    }

    // 2. Initialize external API client
    const octokit = new Octokit({ auth: token });

    try {
        // 3. Make API calls
        const { data: user } = await octokit.rest.users.getAuthenticated();

        console.log(`Authenticated as: ${user.login}`);
        return {
            username: user.login,
            fullName: user.name || "No name set",
            publicRepos: user.public_repos,
        };
    } catch (error) {
        console.error("Failed to fetch user profile:", error);
        throw error;
    }
}

Step 3: Handle errors

Functions should handle errors gracefully and return useful information for debugging.

Try-catch pattern

import { JSONObject, sdk } from "@c1/functions-sdk";

export default async function main(input: JSONObject): Promise<JSONObject> {
  try {
    const userResponse = await sdk.user.get({ id: input.userId as string });
    return { success: true, user: userResponse.user };
  } catch (error) {
    console.error("Failed to get user:", error);
    return {
      success: false,
      error: error.message,
    };
  }
}

Input validation

import { JSONObject } from "@c1/functions-sdk";

export default async function main(input: JSONObject): Promise<JSONObject> {
  // Validate required fields
  if (!input.userId) {
    return { error: "userId is required" };
  }

  const userId = input.userId as string;

  // Your logic here
  return { success: true };
}

Step 4: Test your function

There are two ways to test your function: manual invocation and automated tests.

Manual invocation

Click Run draft to invoke your function with test JSON input.

Provide test input in the JSON editor, for example: {}

View the output and logs in the invocation details drawer.

Automated tests

New functions include a main.test.ts file with a starter template. Write tests using the @c1/test framework:

// main.test.ts
import { JSONObject } from "@c1/functions-sdk";
import { test } from "@c1/test";

export default function registerTests({handler}: {handler: (input: JSONObject) => Promise<JSONObject>}) {
  test("returns a greeting", async ({ equal }) => {
    const result = await handler({ name: "Alice" });
    equal(result.greeting, "Hello, Alice!");
  });

  test("uses default name", async ({ ok }) => {
    const result = await handler({});
    ok(result.greeting);
  });
}

The framework injects your main function as handler, so each test can call it with different inputs.

Click Test draft (or Run tests when viewing published code) to execute your tests.

View individual test results in the dialog. Each test() call becomes its own result with a pass/fail status.

Click on a test result to expand assertion details and logs.

For the full assertion API and more examples, see Testing with @c1/test.

Step 5: Link a service principal for API access

Functions authenticate to the C1 API as a linked service principal. Its role bindings determine what your function can do — read-only, write, or anything in between.

If you don’t already have a suitable service principal, create one. Navigate to Directory > Service principals > New, give it a descriptive name, and assign roles based on what your function needs (for example, Read-Only Administrator for a function that only reads, or Super Administrator for a function that creates or updates resources).

Open your function and click … (the more actions menu) > Link service principal.

Pick the service principal from the list and click Save.

The function authenticates as that service principal on its next invocation. To change what it can do later, edit the service principal’s roles — no function redeploy needed.

Existing functions. Functions that existed before this change have been migrated automatically and linked to a service principal with read-only access. No action is required to keep them running. To grant write access, link them to a different service principal using the steps above.

Step 6: Publish your function

Click Save draft to commit your changes.

Click Publish to make your function available for use across C1.

Once published, your function is available for use in automations or via manual invocation.

Best practices for writing functions

Follow these patterns to write maintainable, debuggable functions.

Use TypeScript interfaces

Define clear input and output types for better code quality:

import { JSONObject } from "@c1/functions-sdk";

interface Input {
  userId: string;
  action: string;
}

interface Output {
  success: boolean;
  message: string;
}

export default async function main(input: JSONObject): Promise<JSONObject> {
  const { userId, action } = input as unknown as Input;

  // Your logic here

  return { success: true, message: "Done" } as Output;
}

Validate inputs

Always validate required parameters before proceeding:

if (!input.userId) {
  return { error: "userId is required" };
}

Use console logging

Log important steps for debugging. Logs are captured and viewable in the UI:

console.log("Processing user:", userId);
console.log("API response:", response);

Handle errors gracefully

Wrap external API calls in try-catch blocks:

try {
  const result = await externalApiCall();
  return { success: true, result };
} catch (error) {
  console.error("External API failed:", error);
  return { success: false, error: error.message };
}

Keep functions focused

Each function should do one thing well. Create multiple functions for complex workflows.

​Use the copilot to write function code

​Step 1: Set up a new function

​Step 2: Write function code

​Basic structure

​Use input parameters

​Access C1 data

​List users

​Get a specific user

​Search users

​Use secrets and configuration

​Set secrets in the UI

​Access secrets in code

​Call external APIs

​Step 3: Handle errors

​Try-catch pattern

​Input validation

​Step 4: Test your function

​Manual invocation

​Automated tests

​Step 5: Link a service principal for API access

​Step 6: Publish your function

​Best practices for writing functions

​Use TypeScript interfaces

​Validate inputs

​Use console logging

​Handle errors gracefully

​Keep functions focused

Use the copilot to write function code

Step 1: Set up a new function

Step 2: Write function code

Basic structure

Use input parameters

Access C1 data

List users

Get a specific user

Search users

Use secrets and configuration

Set secrets in the UI

Access secrets in code

Call external APIs

Step 3: Handle errors

Try-catch pattern

Input validation

Step 4: Test your function

Manual invocation

Automated tests

Step 5: Link a service principal for API access

Step 6: Publish your function

Best practices for writing functions

Use TypeScript interfaces

Validate inputs

Use console logging

Handle errors gracefully

Keep functions focused