Objects API

Comprehensive guide for managing content objects in your Cosmic bucket.

Overview

Objects are the core content items in your Cosmic bucket. They can represent blog posts, pages, products, or any custom content type you've defined.

Available Tools

list_objects

List and filter objects from your bucket with pagination and sorting.

Use Cases:

• Get recent blog posts for a homepage
• List products by category
• Find draft content for review
• Paginate through large content sets

Parameters:

• type_slug (optional): Filter by object type
• limit (optional): Number of objects to return (max 1000)
• skip (optional): Skip objects for pagination
• sort (optional): Sort field and direction
• status (optional): Filter by status (published/draft/any)
• locale (optional): Filter by locale

Example:

{
  "type_slug": "posts",
  "status": "published",
  "limit": 10,
  "sort": "-created_at"
}

get_object

Retrieve a specific object by ID or slug.

Use Cases:

• Get a specific blog post for editing
• Retrieve page content for display
• Fetch product details
• Load localized content

Parameters:

• id (optional): Object ID
• slug (optional): Object slug
• type_slug (required with slug): Object type
• locale (optional): Locale code

Example:

{
  "slug": "my-blog-post",
  "type_slug": "posts"
}

create_object

Create new content objects in your bucket.

Use Cases:

• Publish new blog posts
• Create product pages
• Add team member profiles
• Generate landing pages

Parameters:

• title (required): Object title
• type_slug (required): Object type
• slug (optional): Custom slug (auto-generated if not provided)
• content (optional): HTML or Markdown content
• status (optional): published/draft (default: draft)
• metadata (optional): Custom fields object
• locale (optional): Locale code

Example:

{
  "title": "Getting Started with AI",
  "type_slug": "posts",
  "content": "<h1>Welcome to AI</h1><p>This is an introduction...</p>",
  "status": "published",
  "metadata": {
    "seo_title": "AI Getting Started Guide",
    "meta_description": "Learn the basics of AI",
    "tags": ["ai", "tutorial", "beginner"],
    "featured_image": "https://cosmic-s3.imgix.net/ai-guide.jpg",
    "author": "Jane Doe",
    "reading_time": 5
  }
}

update_object

Update existing objects in your bucket.

Use Cases:

• Edit blog post content
• Update product information
• Change publication status
• Modify metadata

Parameters:

• id (optional): Object ID to update
• slug (optional): Object slug to update
• type_slug (required with slug): Object type
• title (optional): Updated title
• content (optional): Updated content
• status (optional): Updated status
• metadata (optional): Updated metadata
• locale (optional): Locale code

Example:

{
  "slug": "my-blog-post",
  "type_slug": "posts",
  "status": "published",
  "metadata": {
    "tags": ["ai", "tutorial", "updated"],
    "last_modified": "2024-01-15"
  }
}

delete_object

Remove objects from your bucket.

Use Cases:

• Remove outdated content
• Delete draft posts
• Clean up test content
• Remove deprecated products

Parameters:

• id (optional): Object ID to delete
• slug (optional): Object slug to delete
• type_slug (required with slug): Object type

Example:

{
  "slug": "old-blog-post",
  "type_slug": "posts"
}

search_objects

Search through your content using text queries.

Use Cases:

• Find content by keywords
• Search within specific content types
• Locate content for editing
• Build search functionality

Parameters:

• query (required): Search query
• type_slug (optional): Limit search to specific type
• limit (optional): Number of results (max 1000)
• status (optional): Filter by status

Example:

{
  "query": "artificial intelligence",
  "type_slug": "posts",
  "status": "published",
  "limit": 20
}

Common Patterns

Content Management Workflow

1. List drafts: list_objects with status: "draft"
2. Edit content: get_object → modify → update_object
3. Publish: update_object with status: "published"

Blog Management

1. Recent posts: list_objects with type_slug: "posts", sort: "-created_at"
2. Post by slug: get_object with slug and type_slug
3. Search posts: search_objects with type_slug: "posts"

E-commerce

1. Product catalog: list_objects with type_slug: "products"
2. Product details: get_object with product slug
3. Inventory updates: update_object with new metadata

Error Handling

Common error scenarios and solutions:

• Object not found: Check slug spelling and type_slug
• Permission denied: Verify write key for mutations
• Validation error: Check required fields and data types
• Rate limit: Reduce request frequency

Best Practices

1. Use slugs for public content: More readable and SEO-friendly
2. Batch operations: Use pagination for large datasets
3. Status management: Use draft → published workflow
4. Metadata structure: Keep consistent metadata schemas
5. Error handling: Always handle not found and permission errors

Related

• Media API - Managing media files
• Types API - Object type management
• Complete Reference - All tools documentation