Create Column

Add a new column to a sheet. Non-text columns will generate cells for all existing rows. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.

POST /api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns

Create Column

cURL

curl --request POST \
  --url https://api.promptlayer.com/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "title": "<string>",
  "config": {},
  "dependencies": [
    {
      "column_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "reference_type": "value",
      "config_key": "<string>",
      "config_meta": {}
    }
  ]
}
'

import requests

url = "https://api.promptlayer.com/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns"

payload = {
    "title": "<string>",
    "config": {},
    "dependencies": [
        {
            "column_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "reference_type": "value",
            "config_key": "<string>",
            "config_meta": {}
        }
    ]
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    title: '<string>',
    config: {},
    dependencies: [
      {
        column_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        reference_type: 'value',
        config_key: '<string>',
        config_meta: {}
      }
    ]
  })
};

fetch('https://api.promptlayer.com/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.promptlayer.com/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => '<string>',
    'config' => [
        
    ],
    'dependencies' => [
        [
                'column_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'reference_type' => 'value',
                'config_key' => '<string>',
                'config_meta' => [
                                
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.promptlayer.com/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns"

	payload := strings.NewReader("{\n  \"title\": \"<string>\",\n  \"config\": {},\n  \"dependencies\": [\n    {\n      \"column_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"reference_type\": \"value\",\n      \"config_key\": \"<string>\",\n      \"config_meta\": {}\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.promptlayer.com/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"<string>\",\n  \"config\": {},\n  \"dependencies\": [\n    {\n      \"column_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"reference_type\": \"value\",\n      \"config_key\": \"<string>\",\n      \"config_meta\": {}\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.promptlayer.com/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"<string>\",\n  \"config\": {},\n  \"dependencies\": [\n    {\n      \"column_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"reference_type\": \"value\",\n      \"config_key\": \"<string>\",\n      \"config_meta\": {}\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

201

{
  "success": true,
  "column": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sheet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workspace_id": 123,
    "title": "<string>",
    "config": {},
    "position_rank": 123,
    "is_output_column": true
  },
  "cells": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "sheet_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "column_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "row_index": 123,
      "display_value": "<string>",
      "value": "<unknown>",
      "error": "<string>",
      "input_hash": "<string>",
      "updated_at": "2023-11-07T05:31:56Z",
      "request_metrics": {
        "request_count": 123,
        "request_ids": [
          123
        ],
        "latency_ms": 123,
        "price": 123,
        "input_tokens": 123,
        "output_tokens": 123,
        "trace_ids": [
          "<string>"
        ]
      },
      "execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "last_computed_version": 123,
      "error_message": "<string>"
    }
  ],
  "version": 123
}

{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}

{
  "success": false,
  "message": "<string>",
  "error": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Add a new column to a sheet. For non-text columns, cells for all existing rows are created with stale status and queued for computation.

Use dependencies to declare which other columns this column’s config references. PromptLayer enforces a DAG (no cycles allowed) and uses the dependency graph to propagate staleness when upstream cells change. Resolver strings, dependency fields, and config mapping keys are explained in Tables Data Model.

Creating a column creates a new sheet version. The response returns version, the current sheet version count after the column is added.

Authorizations

X-API-KEY · string · header · required

Path Parameters

table_id · string<uuid> · required

sheet_id · string<uuid> · required

Body

application/json

title · string · required

type · enum<string> · required

Available options: text, prompt_template, llm, code, score, comparison, composition

config · object | null

Type-specific column configuration.

dependencies · object[] | null

Column dependency edges for non-text columns.

Show child attributes

Response

201

application/json

Column created

success · boolean

column · object

A column within a Table sheet.

Show child attributes

cells · object[]

Show child attributes

version · integer

Current sheet version_count for this response. It matches the sheet's version_count after any committed changes.