S

Projects API

Manage your projects and retrieve project information

Overview

The Projects API allows you to manage projects within SimplyStack. Projects serve as containers for your blog posts, logs, and storage assets. Each API key is associated with a specific project, providing automatic scoping and security.

🔐 Authentication Scoping

API keys are project-scoped. When using a project API key, all operations are automatically limited to that project. Personal access tokens can access multiple projects if authorized.

Authentication Types

Project API Key

  • • Scoped to a single project
  • • Returns only the associated project
  • • Most common authentication method
  • • Generated per project in settings

Personal Access Token

  • • Can access multiple projects
  • • Returns all user's projects
  • • Requires projects:create scope for creation
  • • Generated in account settings

List Projects

Retrieve a list of projects. The response depends on your authentication type.

GET/api/v1/projects

Request Example

curl -X GET https://simplystack.dev/api/v1/projects \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json"

SDK Example

import { SimplyStackSDK } from "@simplystack-org/sdk";

const sdk = new SimplyStackSDK(process.env.SIMPLYSTACK_API_KEY!);

// Get projects (returns array with single project for project API keys)
const { data: projects, error } = await sdk.getProjects();

if (error) {
  console.error("Failed to fetch projects:", error);
  return;
}

console.log("Projects:", projects);
// For project API keys: [{ id: "project_123", name: "My Project", ... }]
// For personal tokens: [{ id: "proj_1", ... }, { id: "proj_2", ... }]

Response Format

Project API Key Response

{
  "data": [
    {
      "id": "aa9af817-0f46-4d28-a8b6-b6c22e4f44d9",
      "name": "My Project",
      "description": "A sample project for testing",
      "user_id": "user_123",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Personal Access Token Response

{
  "data": [
    {
      "id": "project_1",
      "name": "Production App",
      "description": "Main production application",
      "user_id": "user_123",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    },
    {
      "id": "project_2", 
      "name": "Development Environment",
      "description": "Development and testing",
      "user_id": "user_123",
      "created_at": "2025-01-02T00:00:00.000Z",
      "updated_at": "2025-01-02T00:00:00.000Z"
    }
  ]
}

Get Single Project

Retrieve a specific project by ID. The project must be accessible with your API key.

GET/api/v1/projects/{id}

Request Example

curl -X GET https://simplystack.dev/api/v1/projects/aa9af817-0f46-4d28-a8b6-b6c22e4f44d9 \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json"

SDK Example

const { data: project, error } = await sdk.getProject("aa9af817-0f46-4d28-a8b6-b6c22e4f44d9");

if (error) {
  console.error("Failed to fetch project:", error);
  return;
}

console.log("Project details:", project);

Response

{
  "data": {
    "id": "aa9af817-0f46-4d28-a8b6-b6c22e4f44d9",
    "name": "My Project",
    "description": "A sample project for testing",
    "user_id": "user_123", 
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-01T00:00:00.000Z"
  }
}

Create Project

Create a new project. This endpoint requires a personal access token withprojects:create scope.

⚠️ Permission Required

Project creation requires a personal access token. Project-scoped API keys cannot create new projects.

POST/api/v1/projects

Request Body

{
  "name": "My New Project",           // Required: 2-100 characters
  "description": "Project description" // Optional: max 500 characters
}

Validation Rules

Project Name

  • • Required: Must be provided
  • • Length: 2-100 characters
  • • Characters: Letters, numbers, spaces, hyphens, underscores, dots
  • • Cannot start with: underscore or dash
  • • Pattern: /^[a-zA-Z0-9\s\-_\.]+$/

Description (Optional)

  • • Max length: 500 characters
  • • Type: String

Request Example

curl -X POST https://simplystack.dev/api/v1/projects \
  -H "x-api-key: your_personal_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Project",
    "description": "A project for managing my blog content"
  }'

SDK Example

// Note: This requires a personal access token, not a project API key
const sdk = new SimplyStackSDK(process.env.PERSONAL_ACCESS_TOKEN!);

const { data: result, error } = await sdk.createProject({
  name: "My New Project",
  description: "A project for managing my blog content"
});

if (error) {
  console.error("Failed to create project:", error);
  return;
}

console.log("Created project:", result.project);
if (result.secret) {
  console.log("Project secret generated:", result.secret);
}

Response

{
  "data": {
    "project": {
      "id": "new_project_123",
      "name": "My New Project", 
      "description": "A project for managing my blog content",
      "user_id": "user_123",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    },
    "secret": "abc123def456ghi789..."  // Only if secrets:create scope is present
  }
}

💡 Project Secret

If your personal access token has the secrets:create scope, a project secret will be automatically generated and returned in the response.

Update Project

Update an existing project's name and description.

PUT/api/v1/projects/{id}

Request Body

{
  "name": "Updated Project Name",      // Optional: 2-100 characters
  "description": "Updated description" // Optional: max 500 characters  
}

Request Example

curl -X PUT https://simplystack.dev/api/v1/projects/aa9af817-0f46-4d28-a8b6-b6c22e4f44d9 \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project Name",
    "description": "This project now has an updated description"
  }'

SDK Example

const { data: project, error } = await sdk.updateProject(
  "aa9af817-0f46-4d28-a8b6-b6c22e4f44d9",
  {
    name: "Updated Project Name",
    description: "This project now has an updated description"
  }
);

if (error) {
  console.error("Failed to update project:", error);
  return;
}

console.log("Updated project:", project);

Response

{
  "data": {
    "id": "aa9af817-0f46-4d28-a8b6-b6c22e4f44d9",
    "name": "Updated Project Name",
    "description": "This project now has an updated description",
    "user_id": "user_123",
    "created_at": "2025-01-01T00:00:00.000Z",
    "updated_at": "2025-01-15T10:45:00.000Z"  // Updated timestamp
  }
}

Error Responses

401 Unauthorized

{
  "error": "Authentication failed: Invalid API key"
}

403 Forbidden

{
  "error": "Project creation requires a personal access token. Go to your account settings to create a personal access token."
}

400 Bad Request

{
  "error": "Project name must be at least 2 characters long"
}

404 Not Found

{
  "error": "Project not found"
}

Data Model

interface Project {
  id: string;              // Unique project identifier
  name: string;            // Project name (2-100 chars)
  description?: string;    // Optional description (max 500 chars)
  user_id: string;         // Owner's user ID
  created_at: string;      // ISO 8601 timestamp
  updated_at: string;      // ISO 8601 timestamp  
}