Missions API¶

Endpoints for creating and managing content missions.

The Mission Object¶

{
  "id": "msn_2xK9mPqR4vN8sT3w",
  "name": "Q1 Developer Outreach",
  "description": "Build awareness in the developer community",
  "status": "active",
  "objectives": [
    "Increase brand awareness among developers",
    "Drive traffic to documentation"
  ],
  "platforms": ["twitter", "linkedin"],
  "constraints": {
    "tone": "professional yet approachable",
    "cadence": "daily",
    "posts_per_day": 2,
    "posting_times": ["09:00", "14:00"],
    "timezone": "America/New_York",
    "require_approval": false,
    "budget_cents": 100000,
    "excluded_topics": ["pricing", "competitors"]
  },
  "kpis": [
    {
      "metric": "engagement_rate",
      "target": 4.0,
      "platform": "all"
    }
  ],
  "duration_days": 90,
  "starts_at": "2024-01-15T00:00:00Z",
  "ends_at": "2024-04-14T23:59:59Z",
  "pipeline_job_id": "job_xxx",
  "created_at": "2024-01-10T10:30:00Z",
  "updated_at": "2024-01-10T10:30:00Z"
}

List Missions¶

GET /missions

Retrieve all missions for the current tenant.

Request¶

curl https://api.amp.dev/v1/missions \
  -H "Authorization: Bearer $AMP_API_KEY"

Query Parameters¶

Parameter	Type	Description
`status`	string	Filter by status: `draft`, `active`, `paused`, `completed`
`platform`	string	Filter by platform
`limit`	integer	Results per page (1-100, default 20)
`starting_after`	string	Pagination cursor

Response¶

{
  "data": [
    {
      "id": "msn_2xK9mPqR4vN8sT3w",
      "name": "Q1 Developer Outreach",
      "status": "active",
      "platforms": ["twitter", "linkedin"],
      "starts_at": "2024-01-15T00:00:00Z",
      "ends_at": "2024-04-14T23:59:59Z",
      "created_at": "2024-01-10T10:30:00Z"
    }
  ],
  "has_more": false,
  "total": 1
}

Create Mission¶

POST /missions

Create a new content mission.

Request¶

curl -X POST https://api.amp.dev/v1/missions \
  -H "Authorization: Bearer $AMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Launch Campaign",
    "description": "Generate buzz for new feature release",
    "objectives": [
      "Announce new feature to existing users",
      "Drive feature adoption"
    ],
    "platforms": ["twitter", "linkedin"],
    "constraints": {
      "tone": "excited but professional",
      "cadence": "daily",
      "posts_per_day": 3,
      "require_approval": true
    },
    "kpis": [
      {
        "metric": "engagement_rate",
        "target": 5.0,
        "platform": "all"
      },
      {
        "metric": "link_clicks",
        "target": 1000,
        "platform": "all"
      }
    ],
    "duration_days": 14,
    "start_immediately": true
  }'

Parameters¶

Parameter	Type	Required	Description
`name`	string	Yes	Mission name
`description`	string	No	Detailed description
`objectives`	array	Yes	List of objectives
`platforms`	array	Yes	Target platforms
`constraints`	object	No	Content constraints
`kpis`	array	No	Success metrics
`duration_days`	integer	Yes	Mission duration
`start_immediately`	boolean	No	Start pipeline immediately
`starts_at`	datetime	No	Scheduled start time

Constraints Object¶

Field	Type	Default	Description
`tone`	string	`null`	Desired content tone
`cadence`	string	`daily`	Posting frequency
`posts_per_day`	integer	`1`	Posts per day
`posting_times`	array	`[]`	Preferred times (HH:MM)
`timezone`	string	`UTC`	Timezone for posting times
`require_approval`	boolean	`false`	Require manual approval
`budget_cents`	integer	`null`	Maximum AI spend
`excluded_topics`	array	`[]`	Topics to avoid

KPI Object¶

Field	Type	Required	Description
`metric`	string	Yes	Metric name
`target`	number	Yes	Target value
`platform`	string	No	Platform or `all`

Available Metrics¶

engagement_rate
impressions
clicks / link_clicks
likes
comments
shares
followers_gained
reach

Response¶

{
  "id": "msn_3yL0mPqR5wN9tU4v",
  "name": "Product Launch Campaign",
  "status": "active",
  "pipeline_job_id": "job_8zI4pMsX6yN3qL0w",
  "platforms": ["twitter", "linkedin"],
  "starts_at": "2024-01-15T10:30:00Z",
  "ends_at": "2024-01-29T10:30:00Z",
  "estimated_posts": 42,
  "created_at": "2024-01-15T10:30:00Z"
}

Retrieve Mission¶

GET /missions/:id

Get details for a specific mission.

Request¶

curl https://api.amp.dev/v1/missions/msn_2xK9mPqR4vN8sT3w \
  -H "Authorization: Bearer $AMP_API_KEY"

Query Parameters¶

Parameter	Type	Description
`expand`	string	Include related objects (`content`, `analytics`)

Response¶

Returns the full mission object.

Update Mission¶

PUT /missions/:id

Update an existing mission.

Request¶

curl -X PUT https://api.amp.dev/v1/missions/msn_2xK9mPqR4vN8sT3w \
  -H "Authorization: Bearer $AMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "constraints": {
      "posts_per_day": 3,
      "require_approval": true
    }
  }'

Updatable Fields¶

Field	Notes
`name`	Immediate
`description`	Immediate
`objectives`	Takes effect next cycle
`constraints`	Takes effect next cycle
`kpis`	Affects optimization
`duration_days`	Extends/shortens mission

Response¶

Returns the updated mission object.

Delete Mission¶

DELETE /missions/:id

Delete a mission and all associated content.

Request¶

curl -X DELETE https://api.amp.dev/v1/missions/msn_2xK9mPqR4vN8sT3w \
  -H "Authorization: Bearer $AMP_API_KEY"

Response¶

{
  "id": "msn_2xK9mPqR4vN8sT3w",
  "deleted": true
}

Destructive Action

This permanently deletes the mission and all associated content. Published content remains on platforms but is no longer tracked.

Get Mission Status¶

GET /missions/:id/status

Get real-time status including pipeline progress.

Request¶

curl https://api.amp.dev/v1/missions/msn_2xK9mPqR4vN8sT3w/status \
  -H "Authorization: Bearer $AMP_API_KEY"

Response¶

{
  "mission_id": "msn_2xK9mPqR4vN8sT3w",
  "status": "active",
  "pipeline": {
    "job_id": "job_8zI4pMsX6yN3qL0w",
    "status": "running",
    "current_stage": "content",
    "progress_percent": 65,
    "stages": {
      "intake": {"status": "completed", "duration_ms": 1250},
      "strategy": {"status": "completed", "duration_ms": 45000},
      "content": {"status": "running", "progress_percent": 45},
      "publish": {"status": "pending"},
      "analytics": {"status": "pending"},
      "optimize": {"status": "pending"}
    }
  },
  "content": {
    "generated": 28,
    "pending_review": 5,
    "approved": 23,
    "published": 18,
    "scheduled": 5
  },
  "kpi_progress": [
    {
      "metric": "engagement_rate",
      "target": 4.0,
      "current": 3.8,
      "trend": "improving"
    }
  ],
  "next_publish_at": "2024-01-16T09:00:00Z"
}

Pause Mission¶

POST /missions/:id/pause

Temporarily stop a mission.

Request¶

curl -X POST https://api.amp.dev/v1/missions/msn_2xK9mPqR4vN8sT3w/pause \
  -H "Authorization: Bearer $AMP_API_KEY"

Response¶

{
  "id": "msn_2xK9mPqR4vN8sT3w",
  "status": "paused",
  "paused_at": "2024-01-15T10:30:00Z"
}

Effect:

No new content is generated
Scheduled content is not published
Analytics collection pauses
Duration clock pauses

Resume Mission¶

POST /missions/:id/resume

Resume a paused mission.

Request¶

curl -X POST https://api.amp.dev/v1/missions/msn_2xK9mPqR4vN8sT3w/resume \
  -H "Authorization: Bearer $AMP_API_KEY"

Response¶

{
  "id": "msn_2xK9mPqR4vN8sT3w",
  "status": "active",
  "resumed_at": "2024-01-16T08:00:00Z",
  "adjusted_ends_at": "2024-04-15T23:59:59Z"
}

Effect:

Pipeline resumes from where it stopped
Scheduled content resumes publishing
Duration clock resumes (end date adjusts)

Errors¶

400 Bad Request¶

{
  "error": {
    "code": "invalid_request",
    "message": "At least one platform is required",
    "param": "platforms"
  }
}

404 Not Found¶

{
  "error": {
    "code": "not_found",
    "message": "Mission not found"
  }
}

409 Conflict¶

{
  "error": {
    "code": "conflict",
    "message": "Cannot delete active mission. Pause or complete it first."
  }
}